home *** CD-ROM | disk | FTP | other *** search
/ Libris Britannia 4 / science library(b).zip / science library(b) / UTILITIE / CPU_MEMO / 1648.ZIP / TESS-D.ARC / TESSDOC.LST next >
File List  |  1988-10-02  |  154KB  |  4,756 lines
  1.  
  2.  
  3.  
  4.  
  5.  
  6.  
  7.  
  8.  
  9.                                TesSeRact(TM)
  10.  
  11.  
  12.         A Library of Routines for Developing Ram-Resident Programs
  13.                                      
  14.                                     and
  15.                                      
  16.         A Proposed Standard for Ram-Resident Program Communication
  17.                                      
  18.                                      
  19.                         Documentation Version 1.00
  20.                                July 1, 1988
  21.                                      
  22.                                      
  23.               Copyright (c) 1988, TesSeRact Development Team
  24.                             All Rights Reserved
  25.      
  26.      
  27.              _______
  28.         ____|__     |               (TM)
  29.      --|       |    |-------------------
  30.        |   ____|__  |  Association of
  31.        |  |       |_|  Shareware
  32.        |__|   o   |    Professionals
  33.      -----|   |   |---------------------
  34.           |___|___|    MEMBER
  35.      
  36.      
  37.  
  38.  
  39.                              Table of Contents
  40.  
  41.  
  42.      Preface........................................................iv
  43.           If you've never written a TSR.............................iv
  44.           A note about DOS Versions..................................v
  45.      How to Use This Manual.........................................vi
  46.      Acknowledgements..............................................vii
  47.           The TesSeRact Development Team...........................vii
  48.      Chapter 1.  Legal Stuff.........................................1
  49.           Copyright Notice and Software License......................1
  50.           Warranty...................................................2
  51.           Registered User License....................................2
  52.           Source Code License........................................3
  53.           Required and Suggested Notices.............................3
  54.      Chapter 2.  Shareware Terms.....................................5
  55.           Technical Support..........................................6
  56.  
  57.  
  58.  
  59.                                     -i-
  60.  
  61.  
  62.  
  63.  
  64.  
  65.           Association of Shareware Professionals.....................7
  66.                Standards.............................................7
  67.           Order Form.................................................9
  68.      Chapter 3. History of TesSeRact................................10
  69.      Chapter 4.  TesSeRact Data Structures and Variables............11
  70.           A Quick Note about Graphics Modes.........................11
  71.           TesSeRact Data Structures.................................12
  72.                TsrIntTable..........................................12
  73.                ExtraHot.............................................12
  74.                TsrData..............................................13
  75.                TsrParms.............................................15
  76.           Other PUBLIC, Global Variables............................16
  77.           Equates and Definitions...................................17
  78.      Chapter 5.  TesSeRact External Functions.......................18
  79.           TsrMain...................................................19
  80.           TsrBackCheck..............................................20
  81.           TsrBackProc...............................................21
  82.           TsrTimerProc..............................................22
  83.           TsrUserProc...............................................23
  84.           TsrCleanUp................................................24
  85.      Chapter 6.  TesSeRact Library Routines.........................25
  86.           TsSetStack................................................26
  87.           TsCheckResident...........................................28
  88.           TsDoInit..................................................30
  89.           TsVerify2F................................................32
  90.           TessBeep..................................................33
  91.      Chapter 7.  TesSeRact Multiplex Functions......................34
  92.           Initialization and Information Routines...................34
  93.                Check Install (Function 00h).........................35
  94.                Return User Parameter Pointer (Function 01h).........36
  95.                Check Hotkey (Function 02h)..........................37
  96.                Replace Default Interrupt 24h Handler (Function 03h).38
  97.                Return TesSeRact Data Pointer (Function 04h).........39
  98.                Set Multiple Hot Keys (Function 05h).................40
  99.           TSR Manipulation and Status Routines......................41
  100.                Enable TSR (Function 10h)............................42
  101.                Disable TSR (Function 11h)...........................43
  102.                Release TSR [unload] (Function 12h)..................44
  103.                Restart TSR (Function 13h)...........................45
  104.                Get TSR Status Word (Function 14h)...................46
  105.                Set TSR Status Word (Function 15h)...................47
  106.                Get Indos State at Popup (Function 16h)..............48
  107.           TSR Utility Routines......................................49
  108.                Call User Procedure (Function 20h)...................50
  109.                Stuff Keyboard (Function 21h)........................51
  110.      Chapter 8.  Writing a TesSeRact TSR -- A Tutorial..............53
  111.      Chapter 9.  Language Specifics.................................55
  112.           Turbo C...................................................55
  113.           Microsoft C...............................................56
  114.  
  115.  
  116.  
  117.                                    -ii-
  118.  
  119.  
  120.  
  121.  
  122.  
  123.           Turbo Pascal..............................................57
  124.           Assembler.................................................58
  125.      Chapter 10.  Communicating with the TesSeRact..................59
  126.      Chapter 11.  Writing TesSeRact-Compatible Programs.............65
  127.      Appendix A.  Quick Reference to TesSeRact Functions............69
  128.      Appendix B.  Keyboard Scan Codes...............................70
  129.      Appendix C.  Reporting Bugs....................................71
  130.      Glossary.......................................................72
  131.      Index..........................................................74
  132.  
  133.  
  134.  
  135.  
  136.  
  137.  
  138.  
  139.  
  140.  
  141.  
  142.  
  143.  
  144.  
  145.  
  146.  
  147.  
  148.  
  149.  
  150.  
  151.  
  152.  
  153.  
  154.  
  155.  
  156.  
  157.  
  158.  
  159.  
  160.  
  161.  
  162.  
  163.  
  164.  
  165.  
  166.  
  167.  
  168.  
  169.  
  170.  
  171.  
  172.  
  173.  
  174.  
  175.                                    -iii-
  176.  
  177.  
  178.  
  179.  
  180.  
  181.                                   Preface
  182.  
  183. TesSeRact consists  of two major parts:  a library of routines (.LIB, .OBJ,
  184. .TPU files) that allow a developer to write Ram-Resident, or TSR (Terminate
  185. But Stay  Resident) programs;  and a  set of  functions  that  attempts  to
  186. standardize communication with and between TSR-type programs.
  187.  
  188. The TesSeRact  libraries and modules allow developers to write Ram-Resident
  189. programs with  little or  no knowledge  of the  arcane art of disassembling
  190. DOS, something  that has  been sorely  lacking for  some time.   Among  the
  191. features provided  are easy  use of  hotkeys, simple Ram-Resident routines,
  192. co-resident functions,  and cross-routine  communication facilities.  These
  193. libraries and  modules provided with the TesSeRact package have been tested
  194. with Turbo  C version  1.5, Turbo  Pascal 4.0,  Microsoft C version 5.0 and
  195. 5.1, Microsoft's Macro Assembler 5.0 and 5.1, and OPTASM version 1.0.  Also
  196. note that these routines work on the Heath/Zenith Z-100 computer (using the
  197. ZPC Hardware  Modifications), with  the exception  of  the  keyboard  stuff
  198. routines.   This is  mentioned because this computer is used extensively by
  199. government offices, and is generally considered only marginally compatible.
  200.  
  201. The TesSeRact Standard for Ram-Resident Program Communication is a group of
  202. functions latched  onto DOS'  own Interrupt 2Fh (Multiplex).  DOS uses this
  203. interrupt  to   communicate  with  its  own  TSRs  (PRINT.COM,  ASSIGN.COM,
  204. SHARE.COM), and  the TesSeRact  Development Team felt it was appropriate to
  205. service TSR  programs using  the same  interface.   These functions are all
  206. accessed by  generating an Interrupt 2Fh, with AX=5453 (hex).  Programs may
  207. call these  multiplex functions  directly or may use the functions provided
  208. in the  TESS.LIB or TESS-TP.TPU modules (the assembler version of TesSeRact
  209. does not include callable functions for the Multiplex operations).
  210.  
  211.  
  212.                        If you've never written a TSR
  213.  
  214. Writing TSR or Ram-Resident Programs is not for the beginner, nor is it for
  215. the faint  of heart.  Without a product such as TesSeRact, a programmer can
  216. expect to  spend a  minimum of  six months  learning how  to deal with such
  217. things as  a non-reentrant operating system, hardware specifics, BIOS bugs,
  218. and more.   And  all this  has  nothing  to  do  with  writing  the  actual
  219. application --  this work  will be necessary if a resident program attempts
  220. to do any DOS or BIOS calls from within the resident program.
  221.  
  222. In developing  TesSeRact, and  in the writing of this manual, the TesSeRact
  223. Development Team  has made  certain assumptions  concerning  the  level  of
  224. developer experience.   We  have assumed that developers using this product
  225. have some  knowledge of  the problems  associated with  developing resident
  226. programs.   Note that  it is not necessary to have this background; without
  227. it, however, certain statements will be difficult to comprehend.
  228.  
  229.  
  230.  
  231.  
  232.  
  233.                                    -iv-
  234.  
  235.  
  236.  
  237.  
  238.  
  239. Writing resident  programs, in  general, requires  a basic understanding of
  240. both documented  and undocumented  DOS functions.   This documentation does
  241. not attempt  to detail  the undocumented functions; other material provided
  242. by the  TesSeRact Development  Team may, at some future point, include such
  243. information.
  244.  
  245. The undocumented functions used by the TesSeRact Library routines have been
  246. documented, in some form, by Microsoft in various publications;  the MS-DOS
  247. Encyclopedia, in  particular, has  about the  most complete  discussion  on
  248. resident programs available.  It is not 100% complete, and omits some facts
  249. and observations discovered by some developers, but it's the best.
  250.  
  251. There are  a couple  of other books about memory resident programming and a
  252. number of  magazines have  published articles  on the subject.  If learning
  253. how to  write TSRs  is the goal, some of these are good; others are so poor
  254. as to  be a  waste of  money.   The TesSeRact Development Team will neither
  255. endorse nor oppose any of these books or articles.  Individual team members
  256. will have their own opinions and may feel it appropriate to voice them.
  257.  
  258. The best  way to  learn about  TSRs, in  general, is to study working code.
  259. Books and  articles are  nice, but  generally omit  information because  of
  260. space limitations or the complexity of the subject.  By combining the  code
  261. for the  demonstration  programs,  along  with  the  source  code  for  the
  262. TesSeRact Library  itself, a  developer may  learn more  than  he/she  ever
  263. wanted to know about resident programming, and DOS itself.
  264.  
  265.  
  266.                          A note about DOS Versions
  267.  
  268. TesSeRact has  been tested  on a  wide variety  of DOS versions, ranging in
  269. number from  2.0 to  3.3.   It is  important to note that Microsoft changed
  270. their OEM  licensing agreements  between DOS  versions 2.x  and 3.x.    OEM
  271. versions of  DOS 3.x  must maintain  certain data  areas  and  undocumented
  272. functions in order to provide compatibility with the networking features of
  273. the operating system.  For this reason, resident programs will be much more
  274. reliable when operating under DOS 3.x.
  275.  
  276. The code needed to support DOS 2.x in the TesSeRact Library amounts to less
  277. than 50  bytes; this  deals with  known bugs  and deficiencies.   For  this
  278. reason, support  for DOS  2.x was  left in;  however, some  OEMs  may  have
  279. changed some  things vital  to the  correct functioning of a TesSeRact TSR.
  280. If this situation comes up, please contact the TesSeRact Development Team.
  281.  
  282.  
  283.  
  284.  
  285.  
  286.  
  287.  
  288.  
  289.  
  290.  
  291.                                     -v-
  292.  
  293.  
  294.  
  295.  
  296.  
  297.                           How to Use This Manual
  298.  
  299. The primary  thing to  consider is that NOTHING about TesSeRact is intended
  300. to be  'undocumented.'   All PUBLIC  data areas  and procedures  should  be
  301. described in this documentation.  Please comment on all inconsistencies and
  302. unclear documentation contained herein.
  303.  
  304. Throughout this  document, a  'non-zero' return  from a  function means ANY
  305. value other  than zero  which is  not specifically noted.  A specific value
  306. may not  be valid  in many  cases, especially  on return from the Multiplex
  307. Functions --  the value returned would be dependent on what other Interrupt
  308. 2Fh handlers are installed on the system.
  309.  
  310. This manual  begins with  detailed information  about the various TesSeRact
  311. Data  areas,   all  internal   and  external  TesSeRact  functions,  and  a
  312. description of  each TesSeRact  Multiplex Function.   This is followed by a
  313. short tutorial,  designed to  be language-independent,  on how  to write  a
  314. TesSeRact TSR.  The next chapter describes various specific information for
  315. using TesSeRact  with some  popular language  products.    Note  that  this
  316. chapter will  be expanded  as  more  information  is  gathered  about  more
  317. compilers/assemblers.
  318.  
  319. Next, there is a chapter that may be reproduced (with appropriate copyright
  320. notices) in  user documentation.  It describes, in a narrative form, how to
  321. use the  TesSeRact Multiplex  Functions from  a user  program to  find  out
  322. information about the TSR.
  323.  
  324. The next  chapter is of interest to developers of TSRs who do not intend to
  325. use the  TesSeRact Library  itself.   This chapter  explains how to write a
  326. TesSeRact-compatible TSR  and what Multiplex functions need to be supported
  327. for minimum compatibility.
  328.  
  329. Please  contact   the  TesSeRact   Development  Team   if  you   find   any
  330. inconsistencies or errors in this documentation.
  331.  
  332.  
  333.  
  334.  
  335.  
  336.  
  337.  
  338.  
  339.  
  340.  
  341.  
  342.  
  343.  
  344.  
  345.  
  346.  
  347.  
  348.  
  349.                                    -vi-
  350.  
  351.  
  352.  
  353.  
  354.  
  355.                              Acknowledgements
  356.  
  357. Grateful appreciation  is  expressed  to  CompuServe  Information  Service,
  358. CompuServe's IBM  Software Forums  and their  Sysops, and Computer Language
  359. Magazine for  providing us  with the means to accomplish the development of
  360. TesSeRact.   Without their  gracious assistance, TesSeRact could never have
  361. come into existence.
  362.  
  363. It is  also necessary to thank the beta testers and documentation reviewers
  364. (too numerous  to mention  here)  who  spent  many  hours  helping  produce
  365. TesSeRact.
  366.  
  367. And let's not forget Anne Marie, who suffered through the long evenings and
  368. nights spent getting this product ready.
  369.  
  370. The TesSeRact Development Team:
  371.      
  372.      Chip Rabinowitz
  373.      Jim Kyle
  374.  
  375. TesSeRact is based in part on work done by the Ringmaster Development Team,
  376. in efforts to develop a public domain TSR standard.
  377.  
  378. The Original Ringmaster Development Team:
  379.      
  380.      Team Leader:   Chip Rabinowitz
  381.      Developers:    Lane Ferris
  382.                     Kim Kokkonen
  383.                     Jim Kyle
  384.                     Neil J. Rubenking
  385.                     Barry Simon
  386.                     Rick Wilson
  387.      Contributors:  Thomas Brandenborg
  388.                     Chris Dunford
  389.                     Mark Horvatich
  390.                     John Hensley
  391.                     David Moskowitz
  392.      Advisors:      Robert Bierman
  393.                     David Intersimone
  394.                     Rick Kraus
  395.                     Gary Saxer
  396.      
  397.  
  398.  
  399.  
  400.  
  401.  
  402.  
  403.  
  404.  
  405.  
  406.  
  407.                                    -vii-
  408.  
  409.  
  410. TesSeRact(TM) Documentation (Ver. 1.00)                              Page 1
  411.  
  412.  
  413.  
  414.  
  415.                           Chapter 1.  Legal Stuff
  416.  
  417. Before beginning this description of TesSeRact, there are a number of legal
  418. considerations to dispense with.
  419.  
  420.  
  421.                    Copyright Notice and Software License
  422.  
  423. This  document;   other  accompanying  written  and  disk-based  notes  and
  424. specifications; and all referenced and related program files, demonstration
  425. code and  object modules  accompanying this document are copyrighted by the
  426. TesSeRact Development  Team.   The copyright  owner hereby licenses you to:
  427. use the  software; make as many copies of the software and documentation as
  428. you wish;  give exact  copies of the original to anyone; and distribute the
  429. software and  documentation in  its unmodified  form via  electronic means.
  430. There is no charge for any of the above.
  431.  
  432. You are  specifically prohibited  from charging or requesting donations for
  433. any such  copies, however made.  Exceptions may be granted to organizations
  434. which charge  a small  fee for  materials, handling,  postage  and  general
  435. overhead.  NO   ORGANIZATION  IS   AUTHORIZED  TO  CHARGE  ANY  AMOUNT  FOR
  436. DISTRIBUTION OF  THE SOFTWARE  OR DOCUMENTATION UNDER ANY OTHER CONDITIONS.
  437. Organizations which  charge a fee for distribution of any and all TesSeRact
  438. materials, except  as noted  above or  with the express, written consent of
  439. the TesSeRact  Development Team,  will be  considered in  violation of this
  440. copyright and will be prosecuted to the full extent of the law.
  441.  
  442. In addition,  you are specifically prohibited from making any modifications
  443. to the  TesSeRact Library  Routines and/or  documentation unless you have a
  444. license for  the use of the  code.  Under no circumstances is the copyright
  445. notice embedded in the TesSeRact code to be modified or removed.
  446.  
  447. This is  not free  software.   This license allows you to use this software
  448. without charge  for a period of 30 days.  In order to include this software
  449. as part  of any  product, either commercial, shareware, freeware, or public
  450. domain, registration  is required.   TesSeRact  may not  be included in any
  451. product for  any use  without registration.   Any such use of the TesSeRact
  452. product is in violation of federal copyright laws and will be prosecuted.
  453.  
  454. No copy  of the  software may  be distributed  or given  away without  this
  455. accompanying documentation; this notice must not be removed.
  456.  
  457.  
  458.  
  459.  
  460.  
  461.  
  462.  
  463.  
  464.  
  465.     Copyright (c) 1988, TesSeRact Development Team, All Rights Reserved
  466.  
  467.  
  468. Page 2                              TesSeRact(TM) Documentation (Ver. 1.00)
  469.  
  470.  
  471.                                  Warranty
  472.  
  473. There is  no warranty  of any  kind associated  with this software, and the
  474. copyright owner  is not  liable for  damages of  any kind.   By  using this
  475. software, you  agree to  this.  Every effort has been made by the TesSeRact
  476. Development Team  to make  this product  bug-free.   However, the nature of
  477. software development  is  that  it  is  impossible  to  guarantee  bug-free
  478. software.
  479.  
  480. In the event a verifiable bug is found, the TesSeRact Development Team will
  481. make every  attempt to  repair the  bug as  soon as possible.  A registered
  482. user who reports a valid bug in a release version of TesSeRact will receive
  483. the same rights and privileges that beta testers will receive (described in
  484. a future chapter).
  485.  
  486.  
  487.                           Registered User License
  488.  
  489. Upon receipt of the appropriate registration fee, The TesSeRact Development
  490. Team will  license the  user to  use the  TesSeRact Library  in any and all
  491. products that  the registered  user wishes.   The  registered user may also
  492. distribute unregistered  copies of  the TesSeRact  product,  provided  said
  493. copies include  all materials, documentation and copyright notices provided
  494. with the  original copy  of TesSeRact.  In addition, the embedded copyright
  495. notice within  the code  may not  be removed  from any  copy of  either the
  496. TesSeRact Library,  or from  an executable  program that uses the TesSeRact
  497. Library.   Finally, the  notices described  later in  this document must be
  498. reproduced in both the source code to the registered user's product, and in
  499. the documentation for that product.
  500.  
  501. Users of  TesSeRact are  requested to  formally register  each Ram-Resident
  502. product with the TesSeRact Development Team.  This registration is free and
  503. allows  the  Development  Team  to  maintain  a  list  of  'available'  TSR
  504. Identification Strings.   Although this registration is not required by the
  505. terms of  the  software  license,  it  is  strongly  recommended  to  avoid
  506. conflicts of TSR names.
  507.  
  508.  
  509.  
  510.  
  511.  
  512.  
  513.  
  514.  
  515.  
  516.  
  517.  
  518.  
  519.  
  520.  
  521.  
  522.  
  523.     Copyright (c) 1988, TesSeRact Development Team, All Rights Reserved
  524.  
  525.  
  526. TesSeRact(TM) Documentation (Ver. 1.00)                              Page 3
  527.  
  528.  
  529.                             Source Code License
  530.  
  531. In addition  to the  provisions described  previously, upon  receipt of the
  532. appropriate fee,  the TesSeRact  Development Team licenses the user to use,
  533. but NOT  DISTRIBUTE, the  source code to the TesSeRact Library.  Registered
  534. users may, at their option, modify the TesSeRact Library routines, with the
  535. following exceptions:
  536.      
  537.   1.   The Interrupt 2Fh Multiplex Functions must not be modified in any
  538.        way that  is detectable by an outside program.  The modified code
  539.        must look and execute as if it was the original.
  540.   2.   The embedded  copyright notice, and the associated checksum code,
  541.        may not be removed.
  542.  
  543. Object modules  and executable  programs containing  the modified TesSeRact
  544. Library routines  may be distributed without additional restrictions (other
  545. than described  previously); the  source code may not be distributed in any
  546. form, either in its original or modified form, without the express, written
  547. permission of the TesSeRact Development Team.
  548.  
  549.  
  550.                       Required and Suggested Notices;
  551.  
  552. Under the terms of this license, any product, either commercial, shareware,
  553. freeware, or  public domain,  must include the following notice in both the
  554. program code  and the documentation (Note than an embedded copyright notice
  555. already appears  in the TesSeRact code itself; this notice should be placed
  556. in a commented section of the code):
  557.  
  558. ----------------------------------------
  559.      This product  uses the TesSeRact(TM) Ram-Resident Library and supports
  560.      the TesSeRact  Standard for  Ram-Resident Program  Communication.  For
  561.      information about  TesSeRact, contact  the TesSeRact  Development Team
  562.      at:
  563.      
  564.           TesSeRact Development Team
  565.           c/o Chip Rabinowitz
  566.           2084 Woodlawn Avenue
  567.           Glenside, PA 19038
  568.           1-215-884-3373
  569.      
  570.           Compuserve:         70731,20
  571.           MCIMAIL:  315-5415
  572.      
  573.      This MCIMAIL  Account has  been provided  to the TesSeRact Development
  574.      Team by Borland International, Inc.  The TesSeRact Development Team is
  575.      in no  way associated with Borland International, Inc.  TesSeRact is a
  576.      trademark of the TesSeRact Development Team.
  577.  
  578.  
  579.  
  580.  
  581.     Copyright (c) 1988, TesSeRact Development Team, All Rights Reserved
  582.  
  583.  
  584. Page 4                              TesSeRact(TM) Documentation (Ver. 1.00)
  585.  
  586.  
  587. ----------------------------------------
  588.  
  589. Products that  are written  to support  the TesSeRact Standard which do not
  590. use the  TesSeRact Library routines are encouraged to include the following
  591. notice in their documentation:
  592.  
  593. ----------------------------------------
  594.      This product  supports the  TesSeRact(TM)  Standard  for  Ram-Resident
  595.      Program Communication.   For  information about TesSeRact, contact the
  596.      TesSeRact Development Team at:
  597.      
  598.           TesSeRact Development Team
  599.           c/o Chip Rabinowitz
  600.           2084 Woodlawn Avenue
  601.           Glenside, PA 19038
  602.           1-215-884-3373
  603.      
  604.           Compuserve:         70731,20
  605.           MCIMAIL:  315-5415
  606.      
  607.      This MCIMAIL  Account has  been provided  to the TesSeRact Development
  608.      Team by Borland International, Inc.  The TesSeRact Development Team is
  609.      in no  way associated with Borland International, Inc.  TesSeRact is a
  610.      trademark of the TesSeRact Development Team.
  611.  
  612. ----------------------------------------
  613.  
  614. Developers who  have special  circumstances which would appear to violate a
  615. portion or portions of the TesSeRact License Agreement are urged to contact
  616. the TesSeRact Development Team to work out details of a special license.
  617.  
  618.  
  619.  
  620.  
  621.  
  622.  
  623.  
  624.  
  625.  
  626.  
  627.  
  628.  
  629.  
  630.  
  631.  
  632.  
  633.  
  634.  
  635.  
  636.  
  637.  
  638.  
  639.     Copyright (c) 1988, TesSeRact Development Team, All Rights Reserved
  640.  
  641.  
  642. TesSeRact(TM) Documentation (Ver. 1.00)                              Page 5
  643.  
  644.  
  645.                         Chapter 2.  Shareware Terms
  646.  
  647. TesSeRact is  a user-supported program, also known as 'shareware.'  You are
  648. permitted under  the terms of this license to use this software for 30 days
  649. without any  payments.   If you  continue to  use this  software past  this
  650. point, you must register your copy as outlined below.
  651.  
  652. Registration for  the TesSeRact  Library, in any form, is a one-time fee of
  653. $25.  Payment of this fee entitles you to:
  654.      
  655.      1.   A disk with the latest version of the TesSeRact Library.
  656.      2.   Printed Documentation
  657.      3.   The right  to use  the TesSeRact  Library with  any  Ram-Resident
  658.           program  you   sell  or   distribute,  provided  the  appropriate
  659.           copyright notices appear in your code and documentation.
  660.      4.   Upgrades to future versions of TesSeRact for $10.
  661.  
  662. The complete,  commented source  code to  TesSeRact is  also  available  to
  663. registered users only for a fee of $25.
  664.  
  665. For an  additional $10  per year,  registered users  can receive  a monthly
  666. newsletter  consisting   of  a  list  of  all  registered  products,  their
  667. associated  TSR  Identification  Strings,  and  level  of  support  of  the
  668. TesSeRact Ram-Resident  Program Communication  Standard.   This  newsletter
  669. will also  contain information  about new  versions of TesSeRact, supported
  670. languages, new documentation, etc.
  671.  
  672. Users who  wish to 'test-drive' TesSeRact may do so for a period of 30 days
  673. without charge.   The  TesSeRact Library and Documentation are available on
  674. many electronic  bulletin boards,  commercial electronic networks, and mail
  675. order 'distribution'  houses.   If you  do not  have access to any of these
  676. methods, the TesSeRact Development Team will send you a copy of the Library
  677. and disk-based documentation for $10.  The disk-based documentation differs
  678. from the  printed documentation  only  in  formatting  --  the  content  is
  679. identical.
  680.  
  681. Developers who  have special  circumstances which would appear to violate a
  682. portion or portions of the TesSeRact License Agreement are urged to contact
  683. the TesSeRact Development Team to work out details of a special license.
  684.  
  685. Registered users  of TesSeRact are requested to formally register each Ram-
  686. Resident product with the TesSeRact Development Team.  This registration is
  687. free and  allows us  to maintain  a list  of 'available' TSR Identification
  688. Strings.   Although this  registration is  not required by the terms of the
  689. software license,  it is  strongly recommended  to avoid  conflicts of  TSR
  690. names.  Registered products will be printed in the monthly newsletter.
  691.  
  692. Persons interested  in testing  future versions of TesSeRact should contact
  693. the TesSeRact  Development Team  for information.   Registered  testers who
  694.  
  695.  
  696.  
  697.     Copyright (c) 1988, TesSeRact Development Team, All Rights Reserved
  698.  
  699.  
  700. Page 6                              TesSeRact(TM) Documentation (Ver. 1.00)
  701.  
  702.  
  703. report verifiable  bugs  or  who  make  enhancement  suggestions  that  are
  704. implemented in  TesSeRact receive  an automatic  registration to either the
  705. current or next version of TesSeRact;  or a freesource code license.
  706.  
  707. Developers are  also encouraged  to include  Chapter 10  of this  document,
  708. entitled 'Communicating  with the  TesSeRact,' with  any or  all  of  their
  709. program  documentation.     Chapter   11,   'Writing   TesSeRact-Compatible
  710. Programs,' is  also suitable  for reproduction.   These  chapters, with the
  711. appropriate copyright  notices intact may be reproduced without fee for the
  712. purpose of promoting the TesSeRact Standard.
  713.  
  714.  
  715.                              Technical Support
  716.  
  717. Technical Support  for TesSeRact  is provided free of charge in Subtopic 13
  718. of  the   Computer  Language  Magazine  Forum  (GO  CLMFOR)  on  CompuServe
  719. Information Service.   This  is the  ONLY official  electronic location for
  720. TesSeRact technical  support, although asking a question almost anywhere on
  721. CompuServe will  get an answer.  Technical Support will NOT be provided via
  722. MCIMAIL or CompuServe Easyplex Mail.
  723.  
  724. Members of  the  TesSeRact  Development  Team  may,  at  their  option,  be
  725. available for  lectures and seminars on the product.  Please do not contact
  726. them directly  -- forward  such requests  to the  official address  of  the
  727. development team listed above, or via electronic means.
  728.  
  729. Prepared  programs   currently  exist   for  a  one-to-two  hour  TesSeRact
  730. 'introduction' seminar,  as well  as for a full-day Workshop for developing
  731. applications with TesSeRact.  These programs were designed by the TesSeRact
  732. Team Leader;   Users  Groups, Colleges,  or Corporations interested in such
  733. programs should contact the Development Team.
  734.  
  735.  
  736.  
  737.  
  738.  
  739.  
  740.  
  741.  
  742.  
  743.  
  744.  
  745.  
  746.  
  747.  
  748.  
  749.  
  750.  
  751.  
  752.  
  753.  
  754.  
  755.     Copyright (c) 1988, TesSeRact Development Team, All Rights Reserved
  756.  
  757.  
  758. TesSeRact(TM) Documentation (Ver. 1.00)                              Page 7
  759.  
  760.  
  761.                   Association of Shareware Professionals
  762.  
  763. The Team  Leader of  the TesSeRact  Development Team  is a  member  of  the
  764. Association of  Shareware Professionals  (ASP), an  organization formed  in
  765. April 1987  to strengthen the future of shareware (user supported software)
  766. as an  alternative to  commercial software.   Its  members, all of whom are
  767. programmers who subscribe to a code of ethics, are committed to the concept
  768. of shareware as a method of marketing.
  769.  
  770. The primary goals of the ASP are:
  771.   
  772.   To inform  users about  shareware programs  and about  shareware as  a
  773.        method of distributing and marketing software;
  774.   To encourage broader distribution of shareware through user groups and
  775.        disk dealers  who agree  to identify  and explain  the nature  of
  776.        shareware;
  777.   To assist members in marketing their software;
  778.   To provide  a forum  through which  ASP members may communicate, share
  779.        ideas, and learn from each other; and
  780.   To foster  a high degree of professionalism among shareware authors by
  781.        setting programming,  marketing and  support  standards  for  ASP
  782.        members to follow.
  783.   
  784.   
  785.          Standards for the Association of Shareware Professionals
  786.  
  787. PROGRAMMING STANDARDS:
  788.   
  789.   The program meets the ASP's definition of "shareware" (i.e., it is not
  790.        a commercial demo with major feature disabled, nor a time-limited
  791.        program).
  792.   The program has been thoroughly tested by the author and should not be
  793.        harmful to other files or hardware if used properly.
  794.  
  795. DOCUMENTATION STANDARDS:
  796.   
  797.   Sufficient documentation  is provided to allow the average user to try
  798.        all the major functions of the program.
  799.   Any  discussion   of  the   shareware  concept   and  of  registration
  800.        requirements is done in a professional and positive manner.
  801.  
  802. SUPPORT STANDARDS:
  803.   
  804.   The member  will respond  to people who send registration payments, as
  805.        promised in  the program's  documentation.   At  a  minimum,  the
  806.        member will acknowledge receipt of all payments.
  807.  
  808.  
  809.  
  810.  
  811.  
  812.  
  813.     Copyright (c) 1988, TesSeRact Development Team, All Rights Reserved
  814.  
  815.  
  816. Page 8                              TesSeRact(TM) Documentation (Ver. 1.00)
  817.  
  818.  
  819.   The member  will establish  a procedure  for users to report, and have
  820.        acknowledged, matters such as bug reports, and will describe such
  821.        means in  the documentation  accompanying  all  versions  of  the
  822.        programs.   The author  will respond  to written bug reports from
  823.        registered users when the user provides a self-addressed, stamped
  824.        envelope.
  825.   Known incompatibilities  with other  software or hardware and major or
  826.        unusual program  limitations are  noted in the documentation that
  827.        comes with the shareware (evaluation) program.
  828.  
  829. GENERAL:
  830.   
  831.   Members will  keep the  ASP apprised  of changes  in mailing  address;
  832.        which shareware  programs they  have published  and are currently
  833.        supporting; the  current version  numbers; and  of any changes in
  834.        the status of their programs.
  835.   If a user has a dispute with an ASP member-author, the user may appeal
  836.        to the ASP to mediate for arbitration of the dispute.
  837.  
  838. For more  information about  the Association  of  Shareware  Professionals,
  839. contact Jim  Button, chairman  of the  board of  directors,  at  Compuserve
  840. 71435,2012.
  841.  
  842.  
  843.  
  844.  
  845.  
  846.  
  847.  
  848.  
  849.  
  850.  
  851.  
  852.  
  853.  
  854.  
  855.  
  856.  
  857.  
  858.  
  859.  
  860.  
  861.  
  862.  
  863.  
  864.  
  865.  
  866.  
  867.  
  868.  
  869.  
  870.  
  871.     Copyright (c) 1988, TesSeRact Development Team, All Rights Reserved
  872.  
  873.  
  874. TesSeRact(TM) Documentation (Ver. 1.00)                              Page 9
  875.  
  876.  
  877.                                 Order Form
  878.  
  879.                TesSeRact(TM) Products And Registration Form
  880.  
  881.  
  882.      Name:          ______________________________________
  883.      
  884.      Address:       ______________________________________
  885.      
  886.                     ______________________________________
  887.      
  888.      City:          ______________________________________
  889.      
  890.      State:         __________________________ Zip: ______
  891.      
  892.      Telephone:     ______________________________________
  893.      
  894.      Primary Language:   _________________________________
  895.      
  896.      Item                                      Quantity      Total
  897.      --------------------------------------------------------------
  898.      TesSeRact Registration ($25 each)___________________|_________
  899.      
  900.      TesSeRact Source Code License ($25 each)____________|_________
  901.      
  902.      TesSeRact Trial Disk ($10)__________________________|_________
  903.      
  904.      Monthly Information NewsLetter______________________|_________
  905.         ($10 per year)
  906.      
  907.      Product Identification String (Free!!)______________|_________
  908.         Your ID String: _____________________
  909.         Product Name:   _____________________
  910.      
  911.      --------------------------------------------------------------
  912.      Total Due:                                          |_________
  913.      
  914.      
  915.      Preferred Disk Size:  3.5" ____  5.25" ____
  916.      
  917.      
  918.      Mail Completed Form to:
  919.      
  920.                     TesSeRact Development Team
  921.                     2084 Woodlawn Avenue
  922.                     Glenside, PA 19038
  923.  
  924.  
  925.  
  926.  
  927.  
  928.  
  929.     Copyright (c) 1988, TesSeRact Development Team, All Rights Reserved
  930.  
  931.  
  932. Page 10                             TesSeRact(TM) Documentation (Ver. 1.00)
  933.  
  934.  
  935.          Chapter 3. History of TesSeRact and the Development Team
  936.  
  937. The  TesSeRact  Development  Team  was  organized  in  early  1986  as  the
  938. Ringmaster Development Team for the sole purpose of establishing a standard
  939. to be  shared by TSR program developers, in hopes of reducing the notorious
  940. levels of conflict between such programs.  Participants (all listed earlier
  941. in this  document) represented  the majority  of  leading  independent  TSR
  942. developers.   From the  start, the team conducted its discussions using the
  943. CompuServe Information  System; it  originally met  in a restricted area of
  944. IBMNET and  subsequently moved to the CLMFORUM for public beta tests of the
  945. libraries.
  946.  
  947. The team's  original  goals  were  lofty;  too  much  so,  perhaps,  to  be
  948. achievable within  a reasonable  time span.   The  team envisioned  a total
  949. Applications Program  Interface (API)  for  use  by  both  independent  and
  950. commercial TSR  programs.   Although discussions  with a  leading  software
  951. publisher were held, a consensus developed that no such universal API could
  952. gain acceptance.   After  that conclusion was reached, active participation
  953. dwindled with  the passage  of time, and at one point it appeared to nearly
  954. everyone as  if the project had died.  Establishment of a public discussion
  955. area for  TSR techniques  on the old MSOFT forum breathed new life into the
  956. effort and  brought fresh  contributions from  Thomas Brandenborg  and John
  957. Hensley.   As a result of that discussion, the activity revived with a more
  958. limited goal  of providing a simplified method for creation of TSR programs
  959. using high  level languages and a standard interface for communicating with
  960. such programs.
  961.  
  962. The present package is the outcome of that revived research.  Although most
  963. of the  original team members did not participate in the development of the
  964. current product, their efforts were vital to the TesSeRact library routines
  965. and Standard.   Development continues, and the original goal of a universal
  966. API remains  faintly visible  on the horizon as a rainbow to be chased.  In
  967. the meantime,  TesSeRact as it exists today provides a usable, and we hope,
  968. useful tool to the TSR development community.
  969.  
  970. Future plans  for TesSeRact  include  support  for  Expanded  and  Extended
  971. Memory, and of course, new and improved future versions of DOS.  If support
  972. for the  TesSeRact interface is strong enough, we plan to develop a version
  973. that will run in protected mode as a keyboard monitor under OS/2.
  974.  
  975. In addition,  if there  is enough  support, the  TesSeRact Development Team
  976. would like  to become  the 'clearinghouse'  for  TSR  program  development,
  977. studying options  and continuing  to delve  into undocumented  features  of
  978. operating systems for the PC.
  979.  
  980.  
  981.  
  982.  
  983.  
  984.  
  985.  
  986.  
  987.     Copyright (c) 1988, TesSeRact Development Team, All Rights Reserved
  988.  
  989.  
  990. TesSeRact(TM) Documentation (Ver. 1.00)                             Page 11
  991.  
  992.  
  993.             Chapter 4.  TesSeRact Data Structures and Variables
  994.  
  995.  
  996.                      A Quick Note about Graphics Modes
  997.  
  998. Although  TesSeRact  does  not  support  changing  video  modes  (with  one
  999. exception described below) for resident programs, there are three functions
  1000. TesSeRact DOES  provide to simplify how a TSR interfaces with the multitude
  1001. of graphics cards available.
  1002.  
  1003. First, a  developer can  specify NOPOPGRAPH  (see  below)  as  one  of  the
  1004. parameters to  TsDoInit().   This forces  the TesSeRact  popup routines  to
  1005. check to  see if  the current  video mode is 0, 1, 2, 3 or 7.  If the video
  1006. mode returned  by Interrupt  10h is  not equal  to the  five standard 'text
  1007. modes,' then TesSeRact will issue a TessBeep() function call, and return.
  1008.  
  1009. The second  feature TesSeRact  provides is  detection of  Hercules graphics
  1010. modes.   If the  video mode returned by Interrupt 10h is 7, a check is also
  1011. made for  the presence of a Hercules Graphics Card (or compatible) adapter.
  1012. If the  HGC is  present, and  the current  mode (using routines supplied by
  1013. Hercules) is  graphics, the  TesSeRact routines  will  issue  a  TessBeep()
  1014. function call  and return  to the  underlying application,  just as  if  an
  1015. invalid video mode was detected.
  1016.  
  1017. There is  one exception  to this  rule.   If NOPOPGRAPH  is specified and a
  1018. graphics mode  is detected,  a special  flag is checked to determine if the
  1019. underlying application  is Microsoft Word Version 4.0.  If it is, TesSeRact
  1020. sends an  Alt-F9 character to the keyboard buffer and returns, causing Word
  1021. to switch  into text  mode, if  possible.  TesSeRact then delays a full two
  1022. seconds and  pops up.   If  Word was  unable to  switch to text mode (using
  1023. high-resolution graphics mode on a Herc card, for example), TesSeRact beeps
  1024. and returns.
  1025.  
  1026. The third  and final  provision TesSeRact  makes for  graphics modes  is by
  1027. setting two  variables on  popup:   _TESS_VIDPAGE and _TESS_VIDMODE.  These
  1028. variables (one  byte each)  are set to the values returned by the Interrupt
  1029. 10h call  to get  the video mode.  If a Hercules card is detected and it is
  1030. in graphics mode, then both of these variables are set to 0FFh.
  1031.  
  1032.  
  1033.  
  1034.  
  1035.  
  1036.  
  1037.  
  1038.  
  1039.  
  1040.  
  1041.  
  1042.  
  1043.  
  1044.  
  1045.     Copyright (c) 1988, TesSeRact Development Team, All Rights Reserved
  1046.  
  1047.  
  1048. Page 12                             TesSeRact(TM) Documentation (Ver. 1.00)
  1049.  
  1050.  
  1051.                          TesSeRact Data Structures
  1052.  
  1053. There are  four primary  data structures  used  by  the  TesSeRact  Library
  1054. Routines:  TsrIntTable, ExtraHot, TsrData, and TsrParms.  Each is described
  1055. in detail below.  Note these structures are shown in C language style (from
  1056. TESS.H).   TESS.INC (for  assembler) and  TESS.TP4 (for  Turbo Pascal) have
  1057. descriptions of these structures for use with other languages.
  1058.   
  1059.   
  1060.                                 TsrIntTable
  1061.   
  1062.   struct TsrIntTable {
  1063.      void far * OldVector;         /* Old Interrupt Vector            */
  1064.      unsigned char IntNumber;      /* Interrupt Number                */
  1065.      void near * NewVector;        /* offset of new vector            */
  1066.   };
  1067.  
  1068. The  TsrIntTable   structure  is  used  internally  by  the  two  TesSeRact
  1069. functions, _TESSSETUPINTS  and _TESSRESTOREINTS.   These  are the functions
  1070. used to save/restore the interrupt vectors TesSeRact uses.  All occurrences
  1071. of this structure are inside the TsrData structure described below.
  1072.   
  1073.   
  1074.                                  ExtraHot
  1075.   
  1076.   struct ExtraHot {
  1077.      unsigned char Hotkey;         /* hotkey to check for             */
  1078.      unsigned char ShiftState;     /* shift state for this hot key    */
  1079.      unsigned char FlagByte;       /* flag value to use               */
  1080.                                    /*  MAY NOT BE ZERO!!!             */
  1081.       };
  1082.  
  1083. The ExtraHot  structure used  by the  TsSetExtraHot() function is described
  1084. above.   This data  area is  stored within  the USER  data  area,  and  the
  1085. TesSeRact interrupt  handlers only reference this information through a FAR
  1086. pointer, stored  in the  TsrParms structure.  Please note that the FlagByte
  1087. may not  be  zero  --  that  value  is  reserved  for  the  PRIMARY  hotkey
  1088. combination, which is set up by the call to TsDoInit().
  1089.   
  1090.  
  1091.  
  1092.  
  1093.  
  1094.  
  1095.  
  1096.  
  1097.  
  1098.  
  1099.  
  1100.  
  1101.  
  1102.  
  1103.     Copyright (c) 1988, TesSeRact Development Team, All Rights Reserved
  1104.  
  1105.  
  1106. TesSeRact(TM) Documentation (Ver. 1.00)                             Page 13
  1107.  
  1108.  
  1109.   
  1110.                                   TsrData
  1111.   
  1112.   struct TsrData {                 /* PUBLIC Symbol TESS_GLOBALS      */
  1113.      unsigned char RevLvl;         /* Revision Level of TESS Lib      */
  1114.      unsigned char PopupType;      /* Type of popup in effect         */
  1115.      unsigned char WasInt8;        /* An Interrupt 08h occurred       */
  1116.      unsigned char WasInt13;       /* An Interrupt 13h occurred       */
  1117.      unsigned char IntFlags;       /* Which interrupts are active     */
  1118.      unsigned char SoftFlags;      /* Which soft ints are active      */
  1119.      unsigned char DosVersion;     /* Current major revision of DOS   */
  1120.      unsigned char waitcount;      /* Count to wait before popping up */
  1121.      void far * InDosFlag;         /* Pointer to DOS INDOS flag       */
  1122.      void far * DosCritErr;        /* Pointer to DOS Critical Error   */
  1123.      unsigned short UserPSP;       /* PSP segment of user program     */
  1124.      unsigned short User28PSP;     /* PSP segment of user program     */
  1125.      void far * UserDTA;           /* DTA of interrupted program      */
  1126.      void far * User28DTA;         /* DTA of interrupted program      */
  1127.      unsigned short UserSS;        /* Stack segment of user program   */
  1128.      unsigned short UserSP;        /* Stack pointer of user program   */
  1129.      unsigned short User28SS;      /* Stack segment of user program   */
  1130.      unsigned short User28SP;      /* Stack pointer of user program   */
  1131.      void far * UserInt24;         /* Pointer to use INT 24 handler   */
  1132.      unsigned short OldExtErr[3];  /* Storage for old DOS 3 extended  */
  1133.                                    /*     error information           */
  1134.      unsigned char OldBreak;       /* Old Break Setting               */
  1135.      unsigned char OldVerify;      /* Old Verify Setting              */
  1136.      unsigned char InWord4;        /* Flag to indicate in WORD 4.0    */
  1137.      unsigned char WasWord4;       /* Word 4 special popup flag       */
  1138.      unsigned char NewKbdFlag;     /* Enhanced Keyboard Call in use   */
  1139.      unsigned char Word4Delay;     /* Delay for Word 4                */
  1140.          /* Interrupt vector tables         */
  1141.      struct TsrIntTable Int8;
  1142.      struct TsrIntTable Int9;
  1143.      struct TsrIntTable Int13;
  1144.      struct TsrIntTable Int16;
  1145.      struct TsrIntTable Int1C;
  1146.      struct TsrIntTable Int21;
  1147.      struct TsrIntTable Int28;
  1148.      struct TsrIntTable Int2F;
  1149.      struct TsrIntTable Int1B;
  1150.      struct TsrIntTable Int23;
  1151.      struct TsrIntTable Int24;
  1152.      };
  1153.  
  1154. The TsrData  structure holds virtually all the data used by TesSeRact.  For
  1155. the most part none of these should be modified by an application program.
  1156.  
  1157.  
  1158.  
  1159.  
  1160.  
  1161.     Copyright (c) 1988, TesSeRact Development Team, All Rights Reserved
  1162.  
  1163.  
  1164. Page 14                             TesSeRact(TM) Documentation (Ver. 1.00)
  1165.  
  1166.  
  1167. RevLvl is  always 1  for this  release of  TesSeRact.  PopupType stores the
  1168. current state  of the  INDOS flag  when the _TESSDOPOPUP routine is called.
  1169. Just about  the only  time this  flag is  set on entry to TsrMain() is when
  1170. sitting at  the DOS  prompt.   Some TSR's need to react differently in this
  1171. case (such  as TSR's that spawn other applications), so this information is
  1172. made available.
  1173.  
  1174. The WasInt8  and WasInt13  bytes may be used to detect if a timer tick or a
  1175. disk interrupt  occurred.   The TesSeRact interrupt routines only SET these
  1176. flags --  never clear  them -- so their use is totally up to the individual
  1177. program developer.  (See the  TESSPARK assembler  demonstration program for
  1178. possible uses for these flags.)
  1179.  
  1180. IntFlags and  SoftFlags are  used by  the TesSeRact  routines to  determine
  1181. which interrupts  are currently  being executed  (see definitions for these
  1182. values in  the section on "equates," below).  They should never be modified
  1183. by an application program.
  1184.  
  1185. DosVersion stores the current MAJOR version of DOS (2, 3, etc.).  waitcount
  1186. is used  internally by  the popup routines to delay if INDOS is set -- some
  1187. programs call  DOS in  their own Idle loop, and the delay used by TesSeRact
  1188. (eight timer ticks) appears to be sufficient to ensure popup.
  1189.  
  1190. The next two pointers, InDosFlag and DosCritErr, point to data areas inside
  1191. DOS.  The INDOS flag is a byte signifying whether an Interrupt 21h function
  1192. is active,  and the  Critical Error    is  normally  zero,  unless  DOS  is
  1193. currently servicing an Interrupt 24h (critical error) request.
  1194.  
  1195. Next come  a number of storage areas that are fairly self-explanatory.  The
  1196. variables with  '28' in  their name  are used by the background procedures,
  1197. and the others are used by the popup procedures.
  1198.  
  1199. UserInt24 is  a far pointer (normally set to 0) to a user-defined Interrupt
  1200. 24h handler.   This  value is  set when  a  user  calls  the  TsSetUser24()
  1201. function (TesSeRact Multiplex Function 03h).
  1202.  
  1203. The OldExtErr,  OldBreak and  OldVerify areas are used to store information
  1204. during popup,  and the InWord4, WasWord4, and Word4Delay variables are used
  1205. by the popup routines for the special graphics 'flip' described above.  The
  1206. NewKbdFlag variable  is generally  0 --  however, if an application program
  1207. calls one  of the  'extended' keyboard  functions (Interrupt 16h, Functions
  1208. 10h, 11h or 12h), this byte gets set to 10h during the interrupt call.
  1209.  
  1210. At the  end of  this structure  are the  interrupt tables used by TesSeRact
  1211. routines.
  1212.   
  1213.  
  1214.  
  1215.  
  1216.  
  1217.  
  1218.  
  1219.     Copyright (c) 1988, TesSeRact Development Team, All Rights Reserved
  1220.  
  1221.  
  1222. TesSeRact(TM) Documentation (Ver. 1.00)                             Page 15
  1223.  
  1224.  
  1225.                                  TsrParms
  1226.   
  1227.   
  1228.   struct TsrParms {                /* PUBLIC Symbol TESS_USERPARMS    */
  1229.      char IdCode[8];               /* Unique TSR Identification String*/
  1230.                                    /* NOTE -- NOT NULL-TERMINATED     */
  1231.      unsigned short IdNum;         /* Unique TSR Identification Number*/
  1232.      unsigned long FuncFlags;      /* Bit map of supported functions  */
  1233.      unsigned char HotKey;         /* Hotkey used by TSR for popup    */
  1234.      unsigned char ShiftState;     /* ShiftState used by this TSR pop */
  1235.      unsigned char HotKeyFlag;     /* Which hotkey is in use          */
  1236.      unsigned char ExtraHotCount;  /* Number of Extra Hotkeys to use  */
  1237.      void far * ExtraHotKeys;      /* Pointer to extra hotkeys        */
  1238.      unsigned short TsrStatus;     /* Current TSR Status Flags        */
  1239.      unsigned short TsrPSP;        /* TSR's PSP Segment               */
  1240.      void far * TsrDTA;            /* Pointer to TSR's DTA region     */
  1241.      unsigned short TsrDSeg;       /* TSR's Default Data Segment      */
  1242.      void far * PopupStack;        /* Pointer to Popup Stack Area     */
  1243.      void far * BackStack;         /* Pointer to Background Stack     */
  1244.      };
  1245.  
  1246. The TsrParms  structure is  used to store information about the TSR that is
  1247. necessary for  hotkey detection  and popup control.  All of the information
  1248. in this  structure is placed there by the TesSeRact initialization routines
  1249. -- users  should not  directly write into this area except under controlled
  1250. circumstances and  under VERY  controlled conditions.   For  the most part,
  1251. these variables are self-explanatory, but some comments are in order.
  1252.  
  1253. The IdCode area is eight bytes long -- with no null-terminator required and
  1254. no length byte (as used by Pascal).  Eight bytes are copied from the string
  1255. passed  during   TsCheckResident().    IT  IS  ABSOLUTELY  VITAL  THAT  THE
  1256. IDENTIFICATION STRING  BE PADDED  TO A  MINIMUM OF  EIGHT BYTES!!!   If the
  1257. identification string  is less  than eight bytes, your TSR will not be able
  1258. to find  itself in memory!  Please note that the IdNum is assigned based on
  1259. the number  of other  TesSeRact-aware programs  currently installed  in the
  1260. system.
  1261.  
  1262. FuncFlags  is   a  bit-mapped,  four-byte  variable  that  describes  which
  1263. TesSeRact Multiplex  Functions are supported by this TSR.  For all programs
  1264. written using the TesSeRact Library, this is (hex) FFFFFFFF.  Developers of
  1265. programs that support the TesSeRact Standard should use this double-word to
  1266. identify which  Multiplex functions  they support  (for more  details,  see
  1267. Chapter 11).
  1268.  
  1269. HotKey and ShiftState are used in combination to determine when the program
  1270. should call  TsrMain().   If your program does not use a popup, set both of
  1271. these values  to Hex  0FFh on the call to TsDoInit().  Do not set HotKey to
  1272. ZERO -- this signifies that the program is to pop up when the current shift
  1273. states match  the value of ShiftState, without checking for a hotkey value.
  1274.  
  1275.  
  1276.  
  1277.     Copyright (c) 1988, TesSeRact Development Team, All Rights Reserved
  1278.  
  1279.  
  1280. Page 16                             TesSeRact(TM) Documentation (Ver. 1.00)
  1281.  
  1282.  
  1283. The correct value for HotKey is the Scan Code (listed in Appendix B) of the
  1284. key -- not the value returned by Interrupt 16h.
  1285.  
  1286. The HotKeyFlag  byte may be used by a program to determine which hotkey the
  1287. user hit  (if extra keys are set with TsSetExtraHot()).  This value is ZERO
  1288. if the  primary hotkey  was used;  otherwise, this  is set  to the FlagByte
  1289. specified for the appropriate hotkey in the ExtraHotKeys array.
  1290.  
  1291. The ExtraHotCount tells TesSeRact how many 'extra' hotkeys are used.  These
  1292. hotkeys are  stored in  an array  of ExtraHot  structures;  TsSetExtraHot()
  1293. receives a pointer to this array, and stores it here.
  1294.  
  1295. The TsrStatus  flag word  is a bit-mapped value described in more detail in
  1296. the description of the various equates below.
  1297.  
  1298. Other PUBLIC, Global Variables
  1299.   
  1300.   
  1301.   newint??                         /* TesSeRact Interrupt Vectors     */
  1302.   _TESS_ENDOFDATA                  /* Top of TesSeRact Data Area      */
  1303.                                    /* Beginning of Copyright Notice   */
  1304.   _TESS_CPYRT                      /* Second Part of Copyright Notice */
  1305.   _TESS_VIDMODE                    /* Video Mode when TsrMain() called*/
  1306.   _TESS_VIDPAGE                    /* Video Page when TsrMain() called*/
  1307.   _TESS_INTERRUPTRETURN            /* Dummy 'IRET' instruction        */
  1308.   _TESS_ERROR24                    /* Interrupt 24h Error Code        */
  1309.   _TESS_TEMPPARMS                  /* Temporary Data Storage Location */
  1310.  
  1311. The variables  described above  are other  PUBLIC symbols  available.   The
  1312. newint??   variables    point   to    TesSeRact's    interrupt    handlers.
  1313. _TESS_ENDOFDATA is  the end of TesSeRact's internal data, and the beginning
  1314. of the  copyright notice.   _TESS_CPYRT  is a pointer to the second part of
  1315. the copyright notice.
  1316.  
  1317. _TESS_VIDMODE and  _TESS_VIDPAGE are  used to  store the current video mode
  1318. information on entry to TsrMain() and are described in more detail earlier.
  1319.  
  1320. _TESS_INTERRUPTRETURN is used by the POPFF macro to avoid the problems that
  1321. can  be   caused  by   the  infamous  'popf'  bug  on  early  80286  chips.
  1322. _TESS_ERROR24 is used by TesSeRact's default Interrupt 24h handler to store
  1323. the error  code passed  by  DOS,  and  _TESS_TEMPPARMS  is  used  for  some
  1324. temporary data storage.
  1325.  
  1326.  
  1327.  
  1328.  
  1329.  
  1330.  
  1331.  
  1332.  
  1333.  
  1334.  
  1335.     Copyright (c) 1988, TesSeRact Development Team, All Rights Reserved
  1336.  
  1337.  
  1338. TesSeRact(TM) Documentation (Ver. 1.00)                             Page 17
  1339.  
  1340.  
  1341. Equates and Definitions
  1342.   
  1343.   
  1344.                        Shift State and hotkey flags
  1345.   
  1346.   TSRHOT_??                        /* Definitions for (scan code)     */
  1347.   TSRPOP???                        /* Definitions for shift state     */
  1348.  
  1349. Appendix B  Lists equates  for various scan codes and shift states that can
  1350. be used  by TesSeRact  programs for calling TsDoInit() and TsSetExtraHot().
  1351. These definitions are included in TESS.H, TESS.INC and TESS.TP4.
  1352.   
  1353.   
  1354.                                  TsrFlags
  1355.   
  1356.   TSRUSEPOPUP                      /* User Requests Popup Routine     */
  1357.   TSRUSEBACK                       /* User Requests Background Routine*/
  1358.   TSRUSETIMER                      /* User Requests Timer Routine     */
  1359.   TSRUSEUSER                       /* User Requests User Procedure    */
  1360.   NOPOPGRAPH                       /* User Requests No Pop on Graphics*/
  1361.   NOPOPCOMMAND                     /* User Requests No Pop if INDOS==1*/
  1362.   
  1363.  
  1364. These equates,  described in  the various  include files,  are used for the
  1365. TsrFlags parameter  in the call to TsDoInit().  These values are bit-mapped
  1366. and correspond  directly to  the equates described below for the bit-mapped
  1367. values of TsrStatus.
  1368.   
  1369.   
  1370.                                  TsrStatus
  1371.   
  1372.   HOTKEYON                         /* Hotkey pressed                  */
  1373.   SHIFTSON                         /* Shift states match              */
  1374.   TSRACTIVE                        /* TSR is running in foreground    */
  1375.   INT28ACTIVE                      /* Background routine is active    */
  1376.   
  1377.   POPUPSET                         /* Popup resident routine installed*/
  1378.   BACKSET                          /* Background routine installed    */
  1379.   TIMERSET                         /* Timer procedure installed       */
  1380.   EXTRAHOTSET                      /* Extra hot keys installed        */
  1381.   
  1382.   USERPROCON                       /* User-defined procedure installed*/
  1383.   TSRENABLED                       /* TSR currently enabled           */
  1384.   TSRRELEASED                      /* TSR has been released           */
  1385.   EXTRAINT24                       /* User installed replacement INT24*/
  1386.  
  1387. These equates  describe the bit-mapped contents of the TsrStatus flag word.
  1388. The actual equates are described in more detail in each include file.
  1389.  
  1390.  
  1391.  
  1392.  
  1393.     Copyright (c) 1988, TesSeRact Development Team, All Rights Reserved
  1394.  
  1395.  
  1396. Page 18                             TesSeRact(TM) Documentation (Ver. 1.00)
  1397.  
  1398.  
  1399.                  Chapter 5.  TesSeRact External Functions
  1400.  
  1401. The routines  described in  this chapter  are REQUIRED  user  entry  points
  1402. called by  the TesSeRact  Library Routines.  If you are using the TP4 Unit,
  1403. the TsSetAdrTP4  procedure must  be called with appropriate flags for EVERY
  1404. function you  intend to  use.  Unused functions are initialized by the Unit
  1405. to point  to far  returns. (See  Chapter 10  for a  complete description of
  1406. TsSetAdrTP4.)   Users of  the C  Library should  note that  there are dummy
  1407. functions for  each of  these routines  in the  library (users of Microsoft
  1408. LINK should  use the  '/NOE' linker  option) --  it is  only  necessary  to
  1409. include those  routines in  your that you actually intend to use.  Users of
  1410. the assembler  version MUST  have an  entry point  for each of these PUBLIC
  1411. symbols; at a minimum, these entry points must have a NEAR return.
  1412.  
  1413.  
  1414.  
  1415.  
  1416.  
  1417.  
  1418.  
  1419.  
  1420.  
  1421.  
  1422.  
  1423.  
  1424.  
  1425.  
  1426.  
  1427.  
  1428.  
  1429.  
  1430.  
  1431.  
  1432.  
  1433.  
  1434.  
  1435.  
  1436.  
  1437.  
  1438.  
  1439.  
  1440.  
  1441.  
  1442.  
  1443.  
  1444.  
  1445.  
  1446.  
  1447.  
  1448.  
  1449.  
  1450.  
  1451.     Copyright (c) 1988, TesSeRact Development Team, All Rights Reserved
  1452.  
  1453.  
  1454. TesSeRact(TM) Documentation (Ver. 1.00)                             Page 19
  1455.  
  1456.  
  1457. TsrMain -- Entry Point for Popup Routine
  1458.  
  1459.   This is  the main  entry point for your TSR procedure.  If you specify
  1460.      TSRUSEPOPUP for  the TsrFlags  parameter, this  routine  is  called
  1461.      whenever your  Shift State  and HotKey  are pressed.  (Note that if
  1462.      extra hotkeys are specified using the TsSetExtraHot() function, the
  1463.      ExtraHotCount byte  of  the  TsrParms  data  area  is  set  to  the
  1464.      appropriate value  for the  hotkey selected.)   On  entry  to  this
  1465.      routine, DS  and ES  are the default data segment for your program;
  1466.      all other  registers are  undefined.  The PSP and DTA have been set
  1467.      up for your application, and it is safe to call any runtime library
  1468.      functions as  long as your application uses the 'default' stack, or
  1469.      avoids functions with built-in stack-checking (see other discussion
  1470.      about stack-checking  in the  description of TsSetStack()), as well
  1471.      as any  DOS functions.   Note  that ^C  and ^Break  are  COMPLETELY
  1472.      disabled while  this routine  is in  action.   The scan  codes  are
  1473.      intercepted by  the TesSeRact  Keyboard handler  and prevented from
  1474.      ever reaching the BIOS or DOS.
  1475.  
  1476.   Parameters:
  1477.      None.
  1478.  
  1479.   Returns:
  1480.      None.
  1481.  
  1482.   C Language Usage:
  1483.   
  1484.   void far pascal TsrMain(void);
  1485.  
  1486.   Pascal Usage:
  1487.   
  1488.   {$F+} PROCEDURE TsrMain; {$F-}
  1489.  
  1490.   Assembler Usage:
  1491.   
  1492.   PUBLIC TSRMAIN
  1493.   
  1494.   TSRMAIN  proc near
  1495.      ret
  1496.   TSRMAIN  endp
  1497.   
  1498.  
  1499.  
  1500.  
  1501.  
  1502.  
  1503.  
  1504.  
  1505.  
  1506.  
  1507.  
  1508.  
  1509.     Copyright (c) 1988, TesSeRact Development Team, All Rights Reserved
  1510.  
  1511.  
  1512. Page 20                             TesSeRact(TM) Documentation (Ver. 1.00)
  1513.  
  1514.  
  1515. TsrBackCheck -- Check to see if background processing is requested
  1516.  
  1517.   This function  is a  simple one -- and should be as small as possible.
  1518.      The purpose of this routine is to check appropriate status flags to
  1519.      determine if  background processing  is  needed.    This  is  user-
  1520.      specific,  but  the  following  guidelines  should  be  taken  into
  1521.      account:   this routine is called when it is safe to interrupt DOS,
  1522.      but the stack is the DOS stack, so C Runtime Routines should not be
  1523.      used.   The DS and ES registers point to your default data segment,
  1524.      so it  is possible  to access your own data; you may also call BIOS
  1525.      and DOS  functions safely  (at some  point, a full list of safe DOS
  1526.      functions may  be available -- at the present time, we know of none
  1527.      that do NOT work here).  As mentioned above, the primary purpose of
  1528.      this routine  is to  check and see if full background processing is
  1529.      needed.  If so, a non-zero value is returned; otherwise, a value of
  1530.      zero is  returned.   If non-zero,  the TsrBackProc()  procedure  is
  1531.      called immediately.  TSRUSEBACK must be set for this function to be
  1532.      called.
  1533.  
  1534.   Parameters:
  1535.      None.
  1536.  
  1537.   Returns:
  1538.      Zero signals no background processing is desired
  1539.      Non-Zero results in immediate call to TsrBackProc
  1540.  
  1541.   C Language Usage:
  1542.   
  1543.   unsigned far pascal TsrBackCheck(void);
  1544.  
  1545.   Pascal Usage:
  1546.   
  1547.   {$F+} FUNCTION TsrBackCheck : word; {$F-}
  1548.  
  1549.   Assembler Usage:
  1550.   
  1551.   PUBLIC TSRBACKCHECK
  1552.   
  1553.   TSRBACKCHECK   proc near
  1554.      mov   ax,word ptr ShouldProcess                   ;0     if      no
  1555.   background, 1 for
  1556.      ret                                ;  background processing
  1557.   TSRBACKCHECK   endp
  1558.   
  1559.  
  1560.  
  1561.  
  1562.  
  1563.  
  1564.  
  1565.  
  1566.  
  1567.     Copyright (c) 1988, TesSeRact Development Team, All Rights Reserved
  1568.  
  1569.  
  1570. TesSeRact(TM) Documentation (Ver. 1.00)                             Page 21
  1571.  
  1572.  
  1573. TsrBackProc -- Background Processing Procedure
  1574.  
  1575.   This function  is called  if TsrBackCheck()  returns a non-zero value.
  1576.      It is  safe to call the C Runtimes, DOS, and virtually anything you
  1577.      want.   On entry, ES and DS point to your default Data Segment; you
  1578.      are operating on the stack you specified for background operations,
  1579.      the PSP  and DTA  are yours, and all the DOS status has been saved.
  1580.      Processing here  can be  identical to  TsrMain() processing, except
  1581.      that this  interrupt occurs  asynchronously,  rather  than  as  the
  1582.      result of a hotkey.
  1583.  
  1584.   Parameters:
  1585.      None.
  1586.  
  1587.   Returns:
  1588.      None.
  1589.  
  1590.   C Language Usage:
  1591.   
  1592.   void far pascal TsrBackProc(void);
  1593.  
  1594.   Pascal Usage:
  1595.   
  1596.   {$F+} PROCEDURE TsrBackProc; {$F-}
  1597.  
  1598.   Assembler Usage:
  1599.   
  1600.   PUBLIC   TSRBACKPROC
  1601.   
  1602.   TSRBACKPROC    proc near
  1603.      ret
  1604.   TSRBACKPROC    endp
  1605.  
  1606.  
  1607.  
  1608.  
  1609.  
  1610.  
  1611.  
  1612.  
  1613.  
  1614.  
  1615.  
  1616.  
  1617.  
  1618.  
  1619.  
  1620.  
  1621.  
  1622.  
  1623.  
  1624.  
  1625.     Copyright (c) 1988, TesSeRact Development Team, All Rights Reserved
  1626.  
  1627.  
  1628. Page 22                             TesSeRact(TM) Documentation (Ver. 1.00)
  1629.  
  1630.  
  1631. TsrTimerProc -- Periodic Timer Procedure
  1632.  
  1633.   This function  is called  approximately 18.2  times per second (unless
  1634.      the routine takes too long -- reentrancy is not permitted).  The DS
  1635.      and ES  registers point  to your default data segment, but no other
  1636.      modifications are  made --  you are operating off of the stack that
  1637.      was interrupted by the Interrupt 08h Timer Tick.  DOS functions and
  1638.      Runtime functions  are generally  not safe,  so be  careful.   This
  1639.      routine should be as small and fast as possible in order to receive
  1640.      the maximum  number of  ticks from  the processor and avoid slowing
  1641.      down other background operations.
  1642.  
  1643.   "Too long"  is very subjective.  It completely depends on the hardware
  1644.      being used  and other  factors that can hurt interrupt latency.  In
  1645.      general, spend as little time as possible in this procedure.
  1646.  
  1647.   Parameters:
  1648.      None.
  1649.  
  1650.   Returns:
  1651.      None.
  1652.  
  1653.   C Language Usage:
  1654.   
  1655.   void far pascal TsrTimerProc(void);
  1656.  
  1657.   Pascal Usage:
  1658.   
  1659.   {$F+} PROCEDURE TsrTimerProc; {$F-}
  1660.  
  1661.   Assembler Usage:
  1662.   
  1663.   PUBLIC   TSRTIMERPROC
  1664.   
  1665.   TSRTIMERPROC   proc near
  1666.      ret
  1667.   TSRTIMERPROC   endp
  1668.  
  1669.  
  1670.  
  1671.  
  1672.  
  1673.  
  1674.  
  1675.  
  1676.  
  1677.  
  1678.  
  1679.  
  1680.  
  1681.  
  1682.  
  1683.     Copyright (c) 1988, TesSeRact Development Team, All Rights Reserved
  1684.  
  1685.  
  1686. TesSeRact(TM) Documentation (Ver. 1.00)                             Page 23
  1687.  
  1688.  
  1689. TsrUserProc -- Interface for External Processing
  1690.  
  1691.   This function is designed to allow an external program or procedure to
  1692.      interface with  your TSR.   You  receive DS  (in the  non-assembler
  1693.      version, ES=DS  as well)  pointing to  your data segment, and SS is
  1694.      the Background  Stack.   If a  call to  TsrBackProc() is  currently
  1695.      being processed  when  an  application  calls  this  function,  the
  1696.      TesSeRact functions  loop until the background stack is free.  This
  1697.      is  generally   used  for   inter-process   communication   between
  1698.      applications.   This  routine  is  called  when  a  program  issues
  1699.      TesSeRact Multiplex Function 20h.
  1700.  
  1701.   Note that  the PSP  in effect  when TsrUserProc() is called is the PSP
  1702.      belonging to  the CALLER,  not the  PSP of the TSR.  Although it is
  1703.      safe to  use DOS  functions, the  TSR's file handle table and other
  1704.      PSP data areas are not available.
  1705.  
  1706.   Parameters:
  1707.      UserPtr..................FAR pointer to user-defined data
  1708.  
  1709.   Returns:
  1710.      None.
  1711.  
  1712.   C Language Usage:
  1713.   
  1714.   void far pascal TsrUserProc( void far *UserPtr);
  1715.  
  1716.   Pascal Usage:
  1717.   
  1718.   {$F+} PROCEDURE TsrUserProc( UserPtr : pointer ); {$F-}
  1719.  
  1720.   Assembler Usage:
  1721.   
  1722.   PUBLIC   TSRUSERPROC
  1723.   
  1724.   TSRUSERPROC    proc near
  1725.   ;
  1726.   ;  ES:DI contains FAR pointer to user data
  1727.   ;
  1728.      ret
  1729.   TSRUSERPROC    endp
  1730.  
  1731.  
  1732.  
  1733.  
  1734.  
  1735.  
  1736.  
  1737.  
  1738.  
  1739.  
  1740.  
  1741.     Copyright (c) 1988, TesSeRact Development Team, All Rights Reserved
  1742.  
  1743.  
  1744. Page 24                             TesSeRact(TM) Documentation (Ver. 1.00)
  1745.  
  1746.  
  1747. TsrCleanUp -- Initialize or Clean Up TSR
  1748.  
  1749.   This function is called by the TesSeRact routines to tell the TSR that
  1750.      it is initializing or releasing.  On entry, DS and ES is set to the
  1751.      correct segment,  and SS:SP  is set to the  stack pointer UNLESS it
  1752.      is already  set correctly (for example, the first time this routine
  1753.      is called,  from inside  TsDoInit(), the stack is correct, so it is
  1754.      not adjusted).   It  is safe  to call DOS from inside this routine.
  1755.      The initialization portion of this procedure should be used to call
  1756.      'configuring' functions, such as TsSetExtraHot() or other TesSeRact
  1757.      Multiplex Functions  that cannot  be  called  until  the  Interrupt
  1758.      Handlers have  been installed.   The  shutdown procedure  should be
  1759.      used to  close any open files and call the high-level language exit
  1760.      procedures.   (NOTE:   TP4s exit  procedures are called from within
  1761.      TESSTP.TPU.)
  1762.  
  1763.   Parameters:
  1764.      InitOrShutdown...........0 = Initialize, 1 = ShutDown
  1765.  
  1766.   Returns:
  1767.      None.
  1768.  
  1769.   C Language Usage:
  1770.   
  1771.   void far pascal TsrCleanUp(unsigned InitOrShutdown);
  1772.  
  1773.   Pascal Usage:
  1774.   
  1775.   {$F+} PROCEDURE TsrCleanUp ( RemoveTSR : Boolean ); {$F-}
  1776.  
  1777.   Assembler Usage:
  1778.   
  1779.   PUBLIC   TSRCLEANUP
  1780.   
  1781.   TSRCLEANUP     proc near
  1782.   ;
  1783.   ;  on entry, AX contains the initialize or shutdown flag
  1784.   
  1785.      or    ax,ax
  1786.      jz    do_init
  1787.   do_release:
  1788.      ....
  1789.      jmp   cleanup_exit
  1790.   do_init:
  1791.      ....
  1792.   cleanup_exit:
  1793.      ret
  1794.   TSRCLEANUP     endp
  1795.   
  1796.  
  1797.  
  1798.  
  1799.     Copyright (c) 1988, TesSeRact Development Team, All Rights Reserved
  1800.  
  1801.  
  1802. TesSeRact(TM) Documentation (Ver. 1.00)                             Page 25
  1803.  
  1804.  
  1805.                   Chapter 6.  TesSeRact Library Routines
  1806.  
  1807. The TesSeRact  Library Routines described in this chapter are the functions
  1808. a program  should call  before going  resident.   They are presented in the
  1809. order in  which they  should be  called:   TsSetStack(), TsCheckResident(),
  1810. then TsDoInit().   TsVerify2F()  and TessBeep()  are utility functions also
  1811. included in this chapter.
  1812.  
  1813.  
  1814.  
  1815.  
  1816.  
  1817.  
  1818.  
  1819.  
  1820.  
  1821.  
  1822.  
  1823.  
  1824.  
  1825.  
  1826.  
  1827.  
  1828.  
  1829.  
  1830.  
  1831.  
  1832.  
  1833.  
  1834.  
  1835.  
  1836.  
  1837.  
  1838.  
  1839.  
  1840.  
  1841.  
  1842.  
  1843.  
  1844.  
  1845.  
  1846.  
  1847.  
  1848.  
  1849.  
  1850.  
  1851.  
  1852.  
  1853.  
  1854.  
  1855.  
  1856.  
  1857.     Copyright (c) 1988, TesSeRact Development Team, All Rights Reserved
  1858.  
  1859.  
  1860. Page 26                             TesSeRact(TM) Documentation (Ver. 1.00)
  1861.  
  1862.  
  1863. TsSetStack -- Sets stacks to be used by resident routines
  1864.  
  1865.   This function  tells the TesSeRact functions what data areas to use as
  1866.      stacks.   A value of NULL for the PopUpStack parameter means to use
  1867.      the current  (default) stack  segment  and  stack  pointer  of  the
  1868.      application that  calls this  function.   If you  use NULL  for the
  1869.      PopUpStack, this  should be  the first  call inside main(), and you
  1870.      should use  as few  local variables  in main() as possible to allow
  1871.      the use  of the maximum amount of stack.  Do not specify a value of
  1872.      NULL for  the BackGroundStack  parameter unless  you do  not have a
  1873.      background procedure.   To  use the  C or  Pascal runtime  routines
  1874.      within your  TSR, you  should use stacks of AT LEAST 2K.  Also, all
  1875.      high-level language users should note that unless the default stack
  1876.      is used,  stack-checking will  fail.  Many routines in the standard
  1877.      runtime libraries  provided with  Turbo C,  Microsoft C  and  Turbo
  1878.      Pascal have  been compiled with stack-checking enabled (printf() is
  1879.      a good example) and will FAIL unless the stack is within the limits
  1880.      defined by  the runtime  library.   The demonstration programs show
  1881.      example code  (using undocumented  variables) of how to 'split' the
  1882.      default stack.   Please  note that  with Microsoft  C,  it  is  not
  1883.      possible to  directly set the size of the default stack from within
  1884.      the program  -- this  must be  done with the EXEMOD program (or the
  1885.      /STACK option to LINK) in order to enlarge the stack.
  1886.  
  1887.   Parameters:
  1888.      PopUpStack...............Pointer to Stack for PopUp Procedure
  1889.      BackGroundStack..........Pointer to Stack for Background Procedure
  1890.  
  1891.   Returns:
  1892.      None.
  1893.  
  1894.   C Language Usage:
  1895.   
  1896.   extern void far pascal TsSetStack(
  1897.      void far * PopUpStack,
  1898.      void far * BackGroundStack
  1899.       );
  1900.  
  1901.   Pascal Usage:
  1902.   
  1903.   procedure TsSetStack(
  1904.      var  PopUpStack,
  1905.           BackGroundStack
  1906.      );
  1907.  
  1908.           (continued)
  1909.  
  1910.  
  1911.  
  1912.  
  1913.  
  1914.  
  1915.     Copyright (c) 1988, TesSeRact Development Team, All Rights Reserved
  1916.  
  1917.  
  1918. TesSeRact(TM) Documentation (Ver. 1.00)                             Page 27
  1919.  
  1920.  
  1921.   Assembler Usage:
  1922.   
  1923.   EXTRN    TSSETSTACK:NEAR
  1924.   
  1925.      mov   di,offset PopUpStack
  1926.      mov   si,offset BackGroundStack
  1927.   
  1928.      call  TSSETSTACK
  1929.   
  1930.  
  1931.  
  1932.  
  1933.  
  1934.  
  1935.  
  1936.  
  1937.  
  1938.  
  1939.  
  1940.  
  1941.  
  1942.  
  1943.  
  1944.  
  1945.  
  1946.  
  1947.  
  1948.  
  1949.  
  1950.  
  1951.  
  1952.  
  1953.  
  1954.  
  1955.  
  1956.  
  1957.  
  1958.  
  1959.  
  1960.  
  1961.  
  1962.  
  1963.  
  1964.  
  1965.  
  1966.  
  1967.  
  1968.  
  1969.  
  1970.  
  1971.  
  1972.  
  1973.     Copyright (c) 1988, TesSeRact Development Team, All Rights Reserved
  1974.  
  1975.  
  1976. Page 28                             TesSeRact(TM) Documentation (Ver. 1.00)
  1977.  
  1978.  
  1979. TsCheckResident -- Determine if program has been loaded
  1980.  
  1981.   This function  serves two  primary purposes.  First, it checks to make
  1982.      sure that  the program  identified by  the  passed  IDStr  has  not
  1983.      previously been  loaded.   Then it  begins setting up the TesSeRact
  1984.      data structures  for  this  TSR,  in  preparation  for  a  call  to
  1985.      TsDoInit().  Programs that will not go resident may either use this
  1986.      function call  or may  call the  TesSeRact Multiplex Function (00h)
  1987.      directly.
  1988.  
  1989.   Parameters:
  1990.      IDStr....................Pointer to unique 8-byte Identification
  1991.                               String for this program.  ALL EIGHT bytes
  1992.                               are significant when comparing strings!
  1993.      IDNum....................Pointer to WORD (two-byte) data location
  1994.                               where returned TSR Identification Number
  1995.                               will be placed.
  1996.  
  1997.   Returns:
  1998.      FFFFh indicates  the TSR has already been loaded and may be identified
  1999.      by the Identification Number returned in IDNUM.
  2000.      0 (zero)  indicates the  specified TSR was not found and a new TSR may
  2001.      be installed using the Identification Number returned in IDNUM.
  2002.      If this  function returns FFFFh, and the high byte of IDNUM is FFh, it
  2003.      signifies that the TSR has previously been loaded, but has a 'release'
  2004.      command pending.   This  TSR may  be restarted  with  the  TsRestart()
  2005.      function, or TesSeRact Multiplex Function 13h.
  2006.  
  2007.   C Language Usage:
  2008.   
  2009.   extern unsigned far pascal TsCheckResident(
  2010.      char far * IDStr,
  2011.      unsigned far * IDNum
  2012.      );
  2013.  
  2014.   Pascal Usage:
  2015.   
  2016.   function TsCheckResident(
  2017.       var IDStr,
  2018.           IDNum
  2019.       ) : word;
  2020.  
  2021.           (continued)
  2022.  
  2023.  
  2024.  
  2025.  
  2026.  
  2027.  
  2028.  
  2029.  
  2030.  
  2031.     Copyright (c) 1988, TesSeRact Development Team, All Rights Reserved
  2032.  
  2033.  
  2034. TesSeRact(TM) Documentation (Ver. 1.00)                             Page 29
  2035.  
  2036.  
  2037.   Assembler Usage:
  2038.   
  2039.   EXTRN    TSCHECKRESIDENT:NEAR
  2040.   
  2041.      push  cs
  2042.      pop   es
  2043.      mov   si, offset IdStr
  2044.      mov   di, offset IdNum
  2045.      call  TSRCHECKRESIDENT
  2046.   ;
  2047.   ;  result returned in AX
  2048.   ;
  2049.  
  2050.  
  2051.  
  2052.  
  2053.  
  2054.  
  2055.  
  2056.  
  2057.  
  2058.  
  2059.  
  2060.  
  2061.  
  2062.  
  2063.  
  2064.  
  2065.  
  2066.  
  2067.  
  2068.  
  2069.  
  2070.  
  2071.  
  2072.  
  2073.  
  2074.  
  2075.  
  2076.  
  2077.  
  2078.  
  2079.  
  2080.  
  2081.  
  2082.  
  2083.  
  2084.  
  2085.  
  2086.  
  2087.  
  2088.  
  2089.     Copyright (c) 1988, TesSeRact Development Team, All Rights Reserved
  2090.  
  2091.  
  2092. Page 30                             TesSeRact(TM) Documentation (Ver. 1.00)
  2093.  
  2094.  
  2095. TsDoInit -- Initializes variables and goes resident
  2096.  
  2097.   This function  initializes the  TSR variables and 'goes resident' with
  2098.      the amount of memory you specify and initializes the flags for user
  2099.      routines that you specify.
  2100.  
  2101.   Parameters:
  2102.      HotKey...................Scan Code of Key to use as HotKey (see
  2103.                               Appendix B)
  2104.      ShiftState...............Shift State to be used in combination with
  2105.                               HotKey
  2106.      TsrFlags.................Which Routines are enabled (see Chapter 4)
  2107.      MemoryTop................Number of 16-byte Memory Paragraphs to
  2108.                               keep resident (in the ASM version, this is
  2109.                               the offset of the top of program's memory
  2110.                               that will be kept resident)
  2111.  
  2112.   Returns:
  2113.      Should NEVER  return, unless  DOS' INDOS  flag or  Critical Error Flag
  2114.      could not be found, in which case the return value is 0xFFFF
  2115.  
  2116.   C Language Usage:
  2117.   
  2118.   extern unsigned far pascal TsDoInit(
  2119.      unsigned char HotKey,
  2120.      unsigned char ShiftState,
  2121.      unsigned short TsrFlags,
  2122.      unsigned short MemoryTop
  2123.      );
  2124.  
  2125.   Pascal Usage:
  2126.   
  2127.   function TsDoInit(
  2128.      HotKey,
  2129.      ShiftState,
  2130.      TsrFlags,
  2131.      MemoryTop : word
  2132.      ) : word;
  2133.  
  2134.           (continued)
  2135.  
  2136.  
  2137.  
  2138.  
  2139.  
  2140.  
  2141.  
  2142.  
  2143.  
  2144.  
  2145.  
  2146.  
  2147.     Copyright (c) 1988, TesSeRact Development Team, All Rights Reserved
  2148.  
  2149.  
  2150. TesSeRact(TM) Documentation (Ver. 1.00)                             Page 31
  2151.  
  2152.  
  2153.   Assembler Usage:
  2154.   
  2155.   EXTRN    TSDOINIT:NEAR
  2156.   
  2157.      mov   ah, HotKey
  2158.      mov   al, ShiftState
  2159.      mov   bx, TsrFlags
  2160.      mov   dx, offset MemoryTop
  2161.   
  2162.      call  TSDOINIT
  2163.   ;
  2164.   ;Remember that this function ONLY returns on an error
  2165.   ;
  2166.  
  2167.  
  2168.  
  2169.  
  2170.  
  2171.  
  2172.  
  2173.  
  2174.  
  2175.  
  2176.  
  2177.  
  2178.  
  2179.  
  2180.  
  2181.  
  2182.  
  2183.  
  2184.  
  2185.  
  2186.  
  2187.  
  2188.  
  2189.  
  2190.  
  2191.  
  2192.  
  2193.  
  2194.  
  2195.  
  2196.  
  2197.  
  2198.  
  2199.  
  2200.  
  2201.  
  2202.  
  2203.  
  2204.  
  2205.     Copyright (c) 1988, TesSeRact Development Team, All Rights Reserved
  2206.  
  2207.  
  2208. Page 32                             TesSeRact(TM) Documentation (Ver. 1.00)
  2209.  
  2210.  
  2211. TsVerify2F -- Verify Interrupt 2Fh has valid handler
  2212.  
  2213.   This function is called internally by TsCheckResident() and is used to
  2214.      ensure that  the existing  Interrupt 2Fh  handler is  valid.   This
  2215.      function is  only needed  under DOS  versions 2.x -- beginning with
  2216.      version  3.0,   DOS  pointed  this  interrupt  vector  to  an  IRET
  2217.      instruction.   It is  only necessary  to call  this function  if an
  2218.      application is not using the TsCheckResident() library routine.
  2219.  
  2220.   Parameters:
  2221.      None.
  2222.  
  2223.   Returns:
  2224.      None.
  2225.  
  2226.   C Language Usage:
  2227.   
  2228.   extern void far TsVerify2F(void);
  2229.  
  2230.   Pascal Usage:
  2231.   
  2232.   procedure TsVerify2F;
  2233.  
  2234.   Assembler Usage:
  2235.   
  2236.   EXTRN    TSVERIFY2F:NEAR
  2237.   
  2238.      call  TSVERIFY2F
  2239.  
  2240.  
  2241.  
  2242.  
  2243.  
  2244.  
  2245.  
  2246.  
  2247.  
  2248.  
  2249.  
  2250.  
  2251.  
  2252.  
  2253.  
  2254.  
  2255.  
  2256.  
  2257.  
  2258.  
  2259.  
  2260.  
  2261.  
  2262.  
  2263.     Copyright (c) 1988, TesSeRact Development Team, All Rights Reserved
  2264.  
  2265.  
  2266. TesSeRact(TM) Documentation (Ver. 1.00)                             Page 33
  2267.  
  2268.  
  2269. TessBeep -- Call TesSeRact Internal Beep Routine
  2270.  
  2271.   This function  is used  to allow  a routine  to  call  the  same  BEEP
  2272.      procedure used  by TesSeRact  when it  is unable  to popup.  In the
  2273.      assembler  version  of  TesSeRact,  TessBeep()  is  provided  in  a
  2274.      separate OBJ  module so  that it  may be  completely replaced  by a
  2275.      user-defined procedure.   In  the C  Library, TessBeep()  is in the
  2276.      TSDOBEEP module and also may be replaced by the user.
  2277.  
  2278.   Parameters:
  2279.      None.
  2280.  
  2281.   Returns:
  2282.      None.
  2283.  
  2284.   C Language Usage:
  2285.   
  2286.   extern void far pascal TessBeep(void);
  2287.  
  2288.   Pascal Usage:
  2289.   
  2290.   procedure TessBeep;
  2291.  
  2292.   Assembler Usage:
  2293.   
  2294.   EXTRN    TESSBEEP:near
  2295.   
  2296.      call  TESSBEEP
  2297.  
  2298.  
  2299.  
  2300.  
  2301.  
  2302.  
  2303.  
  2304.  
  2305.  
  2306.  
  2307.  
  2308.  
  2309.  
  2310.  
  2311.  
  2312.  
  2313.  
  2314.  
  2315.  
  2316.  
  2317.  
  2318.  
  2319.  
  2320.  
  2321.     Copyright (c) 1988, TesSeRact Development Team, All Rights Reserved
  2322.  
  2323.  
  2324. Page 34                             TesSeRact(TM) Documentation (Ver. 1.00)
  2325.  
  2326.  
  2327.                  Chapter 7.  TesSeRact Multiplex Functions
  2328.  
  2329. These functions  may be accessed in one of two ways:  First, by calling the
  2330. library routine  described below  directly (this  is not  available in  the
  2331. assembler version).   Second,  by calling  the  appropriate  Interrupt  2Fh
  2332. Multiplex Function call, as described below.
  2333.  
  2334.  
  2335.                   Initialization and Information Routines
  2336.  
  2337.  
  2338.  
  2339. The initialization  and information routines are designed to be called by a
  2340. TSR during  the initialization  portion.  The Check Install function may be
  2341. used instead  of the TsCheckResident() Library Routine described in Chapter
  2342. 6.   The ONLY  Multiplex Functions  that may be called BEFORE TsDoInit() is
  2343. Check Install  or Check Hotkey.  The other functions in this section should
  2344. be called from inside the TsrCleanUp() procedure (initialization portion).
  2345.  
  2346.  
  2347.  
  2348.  
  2349.  
  2350.  
  2351.  
  2352.  
  2353.  
  2354.  
  2355.  
  2356.  
  2357.  
  2358.  
  2359.  
  2360.  
  2361.  
  2362.  
  2363.  
  2364.  
  2365.  
  2366.  
  2367.  
  2368.  
  2369.  
  2370.  
  2371.  
  2372.  
  2373.  
  2374.  
  2375.  
  2376.  
  2377.  
  2378.  
  2379.     Copyright (c) 1988, TesSeRact Development Team, All Rights Reserved
  2380.  
  2381.  
  2382. TesSeRact(TM) Documentation (Ver. 1.00)                             Page 35
  2383.  
  2384.  
  2385. Check Install (Function 00h)
  2386.  
  2387.   This function  must be  called before TsDoInit().  It checks to see if
  2388.      this TSR has already been loaded by comparing the passed IDStr with
  2389.      other compatible  TSRs.    The  primary  difference  between  Check
  2390.      Install  and  TsCheckResident()  is  that  Check  Install  does  no
  2391.      initialization of internal data structures, and should ONLY be used
  2392.      by a  program to  FIND a TSR in memory and get its handle -- NOT to
  2393.      determine if  the TSR  you are  trying to  install has already been
  2394.      loaded.  Please note that under DOS versions 2.x, the Interrupt 2Fh
  2395.      vector is  initialized to  ZERO --  a program calling Interrupt 2Fh
  2396.      will cause  the machine  to crash  if a  TesSeRact TSR has not been
  2397.      loaded.   TsVerify2F() should  be  called  prior  to  calling  this
  2398.      function, or  the application  should make  its own  check for  the
  2399.      validity of Interrupt 2Fh.
  2400.  
  2401.   Parameters:
  2402.      IDStr....................Pointer to unique 8-byte ID String for
  2403.                               this program.  All eight bytes are
  2404.                               significant when comparing strings, so
  2405.                               make sure you specify the values for ALL
  2406.                               eight bytes.
  2407.  
  2408.   Returns:
  2409.      AX=0FFFFh indicates  the TSR  has already  been  loaded,  and  may  be
  2410.      identified by the ID Number returned in the CX register.
  2411.      Any other  value for AX indicates that it is safe to install this TSR,
  2412.      using the identification number returned in the CX register.
  2413.  
  2414.   C Language Usage:
  2415.   
  2416.   See Assembler Usage.
  2417.  
  2418.   Pascal Usage:
  2419.   
  2420.   See Assembler Usage.
  2421.  
  2422.   Assembler Usage:
  2423.   
  2424.      mov   ax,5453h
  2425.      mov   si,offset IDStr
  2426.      xor   cx,cx
  2427.      xor   bx,bx
  2428.      int   2fh
  2429.   ;
  2430.   ;  result returned in AX
  2431.   ;
  2432.   
  2433.  
  2434.  
  2435.  
  2436.  
  2437.     Copyright (c) 1988, TesSeRact Development Team, All Rights Reserved
  2438.  
  2439.  
  2440. Page 36                             TesSeRact(TM) Documentation (Ver. 1.00)
  2441.  
  2442.  
  2443. Return User Parameter Pointer (Function 01h)
  2444.  
  2445.   This function  returns a  pointer to  the  specified  TSR's  parameter
  2446.      block.   This block  contains important  information about the TSR.
  2447.      The structure  is described  in detail in Chapter 4 as the TsrParms
  2448.      structure.   Note that  other TesSeRact Multiplex Functions provide
  2449.      information that  is also available from the data contained in this
  2450.      structure; they  are designed  to be  used as an alternative method
  2451.      for getting information about the TSR.
  2452.  
  2453.   Parameters:
  2454.      TsrIdNum.................Identification Number of TSR to call
  2455.  
  2456.   Returns:
  2457.      NULL = No Matching TSR ID Number found
  2458.      Otherwise, FAR pointer to TsrParms structure
  2459.  
  2460.   C Language Usage:
  2461.   
  2462.   extern struct TsrParms far * far pascal TsGetParms(
  2463.      unsigned short TsrIdNum
  2464.      );
  2465.  
  2466.   Pascal Usage:
  2467.   
  2468.   function TsGetParms(
  2469.      TsrIdNum : word
  2470.      ) : ParmPtr;
  2471.  
  2472.   Assembler Usage:
  2473.   
  2474.      mov   ax,5453h
  2475.      mov   bx,01h
  2476.      mov   cx,TsrIdNum
  2477.      int   2fh
  2478.   
  2479.      or    ax,ax
  2480.      jnz   not_found
  2481.   ;
  2482.   ;  Pointer to data returned in ES:BX
  2483.   ;
  2484.  
  2485.  
  2486.  
  2487.  
  2488.  
  2489.  
  2490.  
  2491.  
  2492.  
  2493.  
  2494.  
  2495.     Copyright (c) 1988, TesSeRact Development Team, All Rights Reserved
  2496.  
  2497.  
  2498. TesSeRact(TM) Documentation (Ver. 1.00)                             Page 37
  2499.  
  2500.  
  2501. Check Hotkey (Function 02h)
  2502.  
  2503.   This function  is used  to determine  if the selected hotkey is not in
  2504.      use by  any other  TesSeRact-compatible  TSR.    At  present,  this
  2505.      function checks  only for  PRIMARY Hotkeys and does not compare the
  2506.      'shift state'  required for  activation, assuming  that a  TSR that
  2507.      uses ATL-T to pop up would conflict with a TSR that uses Shift-Alt-
  2508.      T.
  2509.  
  2510.   Parameters:
  2511.      HotKey...................Scan Code of key to use for Hotkey
  2512.  
  2513.   Returns:
  2514.      FFFFh -- Hotkey conflicts with TSR already loaded
  2515.      Anything else signifies it is safe to install a TSR with this hotkey.
  2516.  
  2517.   C Language Usage:
  2518.   
  2519.   extern unsigned far pascal TsCheckHotkey(
  2520.      unsigned char HotKey
  2521.      );
  2522.  
  2523.   Pascal Usage:
  2524.   
  2525.   function TsCheckHotkey(
  2526.      HotKey : word
  2527.      ) : word;
  2528.  
  2529.   Assembler Usage:
  2530.   
  2531.      mov   ax,5453h
  2532.      mov   bx,02h
  2533.      mov   cl,HotKey
  2534.      int   2fh
  2535.   ;
  2536.   ;  result returned in AX
  2537.   ;
  2538.  
  2539.  
  2540.  
  2541.  
  2542.  
  2543.  
  2544.  
  2545.  
  2546.  
  2547.  
  2548.  
  2549.  
  2550.  
  2551.  
  2552.  
  2553.     Copyright (c) 1988, TesSeRact Development Team, All Rights Reserved
  2554.  
  2555.  
  2556. Page 38                             TesSeRact(TM) Documentation (Ver. 1.00)
  2557.  
  2558.  
  2559. Replace Default Interrupt 24h Handler (Function 03h)
  2560.  
  2561.   This function  is used to replace the TesSeRact default Critical Error
  2562.      Handler routine.   The default procedure returns a FAIL code to the
  2563.      calling program.  This routine allows the developer to replace that
  2564.      function with  his own.  Registers on entry to this routine are the
  2565.      same as  described in  the DOS  Technical Reference Manual, and all
  2566.      conditions described  there are  in effect.   Once control has been
  2567.      passed to  this routine,  it is  the developer's  responsibility to
  2568.      return back  to DOS  or the calling program.  Please note that this
  2569.      routine, if  implemented by  the developer,  cannot be called until
  2570.      the TSR  has been  enabled by  TsDoInit();   this should  be called
  2571.      during the initialization phase of TsrCleanup().
  2572.  
  2573.   Parameters:
  2574.      TsrIdNum.................Identification Number of TSR to call
  2575.      UserCritErrProc..........Pointer to Function to call
  2576.  
  2577.   Returns:
  2578.      Non-Zero -- Unable to install handler -- invalid ID Number
  2579.      Zero -- Success
  2580.  
  2581.   C Language Usage:
  2582.   
  2583.   extern unsigned far pascal TsSetUser24(
  2584.      unsigned short TsrIdNum,
  2585.      void (far *UserCritErrProc) (void)
  2586.      );
  2587.  
  2588.   Pascal Usage:
  2589.   
  2590.   function TsSetUser24(
  2591.      TsrIdNum : word;
  2592.      UserCritErrProc : pointer
  2593.      ) : integer;
  2594.  
  2595.   Assembler Usage:
  2596.   
  2597.      mov   ax,5453h
  2598.      mov   bx,03h
  2599.      lds   si,UserCritErrProc
  2600.      int   2fh
  2601.   ;
  2602.   ;  result returned in AX
  2603.   ;
  2604.  
  2605.  
  2606.  
  2607.  
  2608.  
  2609.  
  2610.  
  2611.     Copyright (c) 1988, TesSeRact Development Team, All Rights Reserved
  2612.  
  2613.  
  2614. TesSeRact(TM) Documentation (Ver. 1.00)                             Page 39
  2615.  
  2616.  
  2617. Return TesSeRact Data Pointer (Function 04h)
  2618.  
  2619.   This function  returns a  pointer to the specified TSR's internal data
  2620.      areas.   This block  contains internal  information about  the TSR.
  2621.      The structure  is described  in detail  in Chapter 4 as the TsrData
  2622.      structure.   Note that  other TesSeRact Multiplex Functions provide
  2623.      information that  is also available from the data contained in this
  2624.      structure; they  are designed  to be  used as an alternative method
  2625.      for getting information about the TSR.
  2626.  
  2627.   Parameters:
  2628.      TsrIdNum.................Identification Number of TSR to call
  2629.  
  2630.   Returns:
  2631.      NULL = No Matching TSR ID Number found
  2632.      Otherwise, FAR pointer to TsrData structure
  2633.      
  2634.  
  2635.   C Language Usage:
  2636.   
  2637.   extern struct TsrData far * far pascal TsGetData(
  2638.      unsigned short TsrIdNum
  2639.      );
  2640.  
  2641.   Pascal Usage:
  2642.   
  2643.   function TsGetData(
  2644.      TsrIdNum : word
  2645.      ) : DataPtr
  2646.  
  2647.   Assembler Usage:
  2648.   
  2649.      mov   ax,5453h
  2650.      mov   bx,04h
  2651.      mov   cx,TsrIdNum
  2652.      int   2fh
  2653.   
  2654.      or    ax,ax
  2655.      jnz   not_found
  2656.   ;
  2657.   ;  Pointer returned in ES:BX
  2658.   ;
  2659.  
  2660.  
  2661.  
  2662.  
  2663.  
  2664.  
  2665.  
  2666.  
  2667.  
  2668.  
  2669.     Copyright (c) 1988, TesSeRact Development Team, All Rights Reserved
  2670.  
  2671.  
  2672. Page 40                             TesSeRact(TM) Documentation (Ver. 1.00)
  2673.  
  2674.  
  2675. Set Multiple Hot Keys (Function 05h)
  2676.  
  2677.   This function  is used  to set  multiple  hotkeys  for  a  TSR.    The
  2678.      TsDoInit() function  only has facilities for a single HotKey/Shift-
  2679.      State  combination,  which  should  suffice  for  the  majority  of
  2680.      resident programs.   However,  many programmers want the ability to
  2681.      set up  multiple hotkeys.    Please  note  that  this  routine,  if
  2682.      implemented by  the developer,  cannot be  called until the TSR has
  2683.      been enabled  by TsDoInit();   this  should be  called  during  the
  2684.      initialization phase of TsrCleanup().
  2685.  
  2686.   Parameters:
  2687.      TsrIdNum.................Identification Number of TSR to call
  2688.      count....................Number of Extra Keys to install
  2689.      ExtraHotKeys.............Pointer to an array of struct ExtraHots
  2690.  
  2691.   Returns:
  2692.      Non-Zero -- Unable to install hotkeys -- invalid ID Number
  2693.      Zero -- Success
  2694.      
  2695.  
  2696.   C Language Usage:
  2697.   
  2698.   extern unsigned far pascal TsSetExtraHot(
  2699.      unsigned short TsrIdNum,
  2700.      unsigned char count,
  2701.      struct ExtraHot far *ExtraHotKeys
  2702.   );
  2703.  
  2704.   Pascal Usage:
  2705.   
  2706.   function TsSetExtraHot(
  2707.      TsrIdNum  : word;
  2708.      Count     : byte;
  2709.      ExtraKeys : pointer
  2710.   ) : word;
  2711.  
  2712.   Assembler Usage:
  2713.   
  2714.      mov   ax,5453h
  2715.      mov   bx,05h
  2716.      mov   cx,TsrIdNum
  2717.      mov   dl,count
  2718.      lds   si,ExtraHotKeys
  2719.      int   2fh
  2720.   ;
  2721.   ;  result returned in AX
  2722.   ;
  2723.  
  2724.  
  2725.  
  2726.  
  2727.     Copyright (c) 1988, TesSeRact Development Team, All Rights Reserved
  2728.  
  2729.  
  2730. TesSeRact(TM) Documentation (Ver. 1.00)                             Page 41
  2731.  
  2732.  
  2733.                    TSR Manipulation and Status Routines
  2734.  
  2735.  
  2736.  
  2737. The TesSeRact  Multiplex Functions  in this group are designed to be called
  2738. by both  resident and  non-resident portions  of applications.  Appropriate
  2739. use of  these functions,  many of  which can  be directly  applied  to  the
  2740. TesSeRact Data  Areas, makes  communication and  manipulation of  TesSeRact
  2741. programs simple.
  2742.  
  2743.  
  2744.  
  2745.  
  2746.  
  2747.  
  2748.  
  2749.  
  2750.  
  2751.  
  2752.  
  2753.  
  2754.  
  2755.  
  2756.  
  2757.  
  2758.  
  2759.  
  2760.  
  2761.  
  2762.  
  2763.  
  2764.  
  2765.  
  2766.  
  2767.  
  2768.  
  2769.  
  2770.  
  2771.  
  2772.  
  2773.  
  2774.  
  2775.  
  2776.  
  2777.  
  2778.  
  2779.  
  2780.  
  2781.  
  2782.  
  2783.  
  2784.  
  2785.     Copyright (c) 1988, TesSeRact Development Team, All Rights Reserved
  2786.  
  2787.  
  2788. Page 42                             TesSeRact(TM) Documentation (Ver. 1.00)
  2789.  
  2790.  
  2791. Enable TSR (Function 10h)
  2792.  
  2793.   This function  calls the  TesSeRact Multiplex interrupt to turn on the
  2794.      'enable' flag  for a  TSR.   It is  the functional  opposite of the
  2795.      TsDisable() function.
  2796.  
  2797.   Parameters:
  2798.      TsrIdNum.................Identification Number of TSR to call
  2799.  
  2800.   Returns:
  2801.      Non-Zero -- Unable to enable TSR -- invalid ID Number
  2802.      Zero -- Success
  2803.  
  2804.   C Language Usage:
  2805.   
  2806.   extern unsigned pascal TsEnable(
  2807.      unsigned short TsrIdNum
  2808.      );
  2809.  
  2810.   Pascal Usage:
  2811.   
  2812.   procedure TsEnable(
  2813.      TsrIdNum : word
  2814.      );
  2815.  
  2816.   Assembler Usage:
  2817.   
  2818.      mov   ax,5453h
  2819.      mov   bx,10h
  2820.      mov   cx,TsrIdNum
  2821.      int   2fh
  2822.   ;
  2823.   ;  result returned in AX
  2824.   ;
  2825.  
  2826.  
  2827.  
  2828.  
  2829.  
  2830.  
  2831.  
  2832.  
  2833.  
  2834.  
  2835.  
  2836.  
  2837.  
  2838.  
  2839.  
  2840.  
  2841.  
  2842.  
  2843.     Copyright (c) 1988, TesSeRact Development Team, All Rights Reserved
  2844.  
  2845.  
  2846. TesSeRact(TM) Documentation (Ver. 1.00)                             Page 43
  2847.  
  2848.  
  2849. Disable TSR (Function 11h)
  2850.  
  2851.   This function turns  off the 'enable' flag for a TSR.  The TSR remains
  2852.      in memory,  but it  cannot pop  up,  nor  will  any  of  its  other
  2853.      operations be  active.   As soon as it is enabled again, actions on
  2854.      'hold' (like  keys stuffed  into the  buffer) will immediately take
  2855.      place.  It is the functional opposite of the TsEnable() function.
  2856.  
  2857.   Parameters:
  2858.      TsrIdNum.................Identification Number of TSR to call
  2859.  
  2860.   Returns:
  2861.      Non-Zero -- Unable to disable TSR -- invalid ID Number
  2862.      Zero -- Success
  2863.  
  2864.   C Language Usage:
  2865.   
  2866.   extern unsigned pascal TsDisable(
  2867.      unsigned short TsrIdNum
  2868.      );
  2869.  
  2870.   Pascal Usage:
  2871.   
  2872.   procedure TsDisable(
  2873.      TsrIdNum : word
  2874.      );
  2875.  
  2876.   Assembler Usage:
  2877.   
  2878.      mov   ax,5453h
  2879.      mov   bx,11h
  2880.      mov   cx,TsrIdNum
  2881.      int   2fh
  2882.   ;
  2883.   ;  result returned in AX
  2884.   ;
  2885.  
  2886.  
  2887.  
  2888.  
  2889.  
  2890.  
  2891.  
  2892.  
  2893.  
  2894.  
  2895.  
  2896.  
  2897.  
  2898.  
  2899.  
  2900.  
  2901.     Copyright (c) 1988, TesSeRact Development Team, All Rights Reserved
  2902.  
  2903.  
  2904. Page 44                             TesSeRact(TM) Documentation (Ver. 1.00)
  2905.  
  2906.  
  2907. Release TSR [unload] (Function 12h)
  2908.  
  2909.   This function  allows for  releasing a TSR from memory at the earliest
  2910.      possible moment.   In  order for a TSR to remove itself, it must be
  2911.      the last  interrupt in the interrupt chain for *every* interrupt it
  2912.      uses.   If another  program is  loaded  that  interferes  with  the
  2913.      interrupt chain,  the TesSeRact  Library will wait until it is safe
  2914.      to remove your TSR from RAM.
  2915.  
  2916.   Parameters:
  2917.      TsrIdNum.................Identification Number of TSR to call
  2918.  
  2919.   Returns:
  2920.      Non-Zero -- Unable to release TSR -- invalid ID Number
  2921.      Zero -- Success
  2922.  
  2923.   C Language Usage:
  2924.   
  2925.   extern unsigned pascal TsRelease(
  2926.      unsigned short TsrIdNum
  2927.      );
  2928.  
  2929.   Pascal Usage:
  2930.   
  2931.   procedure TsRelease(
  2932.      TsrIdNum : word
  2933.      );
  2934.  
  2935.   Assembler Usage:
  2936.   
  2937.      mov   ax,5453h
  2938.      mov   bx,12h
  2939.      mov   cx,TsrIdNum
  2940.      int   2fh
  2941.   ;
  2942.   ;  result returned in AX
  2943.   ;
  2944.  
  2945.  
  2946.  
  2947.  
  2948.  
  2949.  
  2950.  
  2951.  
  2952.  
  2953.  
  2954.  
  2955.  
  2956.  
  2957.  
  2958.  
  2959.     Copyright (c) 1988, TesSeRact Development Team, All Rights Reserved
  2960.  
  2961.  
  2962. TesSeRact(TM) Documentation (Ver. 1.00)                             Page 45
  2963.  
  2964.  
  2965. Restart TSR (Function 13h)
  2966.  
  2967.   This function is used to 'restart' a TSR that has been released but is
  2968.      still physically  in memory.   Note that TsrCleanUp() is NOT called
  2969.      again for  initialization,  because  the  program  has  never  been
  2970.      notified through the same routine that it was removed.
  2971.  
  2972.   Parameters:
  2973.      TsrIdNum.................Identification Number of TSR to call
  2974.  
  2975.   Returns:
  2976.      Non-Zero -- Unable to restart TSR -- invalid ID Number
  2977.      Zero -- Success
  2978.  
  2979.   C Language Usage:
  2980.   
  2981.   extern unsigned pascal TsRestart(
  2982.      unsigned short TsrIdNum
  2983.      );
  2984.  
  2985.   Pascal Usage:
  2986.   
  2987.   procedure TsRestart(
  2988.      TsrIdNum : word
  2989.      );
  2990.  
  2991.   Assembler Usage:
  2992.   
  2993.      mov   ax,5453h
  2994.      mov   bx,13h
  2995.      mov   cx,TsrIdNum
  2996.      int   2fh
  2997.   ;
  2998.   ;  result returned in AX
  2999.   ;
  3000.  
  3001.  
  3002.  
  3003.  
  3004.  
  3005.  
  3006.  
  3007.  
  3008.  
  3009.  
  3010.  
  3011.  
  3012.  
  3013.  
  3014.  
  3015.  
  3016.  
  3017.     Copyright (c) 1988, TesSeRact Development Team, All Rights Reserved
  3018.  
  3019.  
  3020. Page 46                             TesSeRact(TM) Documentation (Ver. 1.00)
  3021.  
  3022.  
  3023. Get TSR Status Word (Function 14h)
  3024.  
  3025.   This function  is used  to determine what the current status flags are
  3026.      for the specified TSR.  The possible values are the same as for the
  3027.      TsrFlags parameter  to TsDoInit().  Note also that this status word
  3028.      may also  be accessed directly by modifying the TsrStatus word from
  3029.      the TsrParms  Data Structure.   The  high-level language  functions
  3030.      specifically return  the status  flags if  no error  occurred;  the
  3031.      assembler version is atypical in that this value is not returned in
  3032.      AX, as expected.
  3033.  
  3034.   Parameters:
  3035.      TsrIdNum.................Identification Number of TSR to call
  3036.  
  3037.   Returns:
  3038.      FFFFh - invalid TSR ID Code
  3039.      Any other value is current status flags
  3040.  
  3041.   C Language Usage:
  3042.   
  3043.   extern unsigned far pascal TsGetStat(
  3044.      unsigned short TsrIdNum
  3045.      );
  3046.  
  3047.   Pascal Usage:
  3048.   
  3049.   function TsGetStat(
  3050.      TsrIdNum : word
  3051.      ) : word;
  3052.  
  3053.   Assembler Usage:
  3054.   
  3055.      mov   ax,5453h
  3056.      mov   bx,14h
  3057.      mov   cx,TsrIdNum
  3058.      int   2fh
  3059.      or    ax,ax
  3060.      jnz   invalid_idnum
  3061.   ;
  3062.   ;  result returned in BX
  3063.   ;
  3064.  
  3065.  
  3066.  
  3067.  
  3068.  
  3069.  
  3070.  
  3071.  
  3072.  
  3073.  
  3074.  
  3075.     Copyright (c) 1988, TesSeRact Development Team, All Rights Reserved
  3076.  
  3077.  
  3078. TesSeRact(TM) Documentation (Ver. 1.00)                             Page 47
  3079.  
  3080.  
  3081. Set TSR Status Word (Function 15h)
  3082.  
  3083.   This function  is used  to modify  the existing  status flags  for the
  3084.      specified TSR.   The  possible values  are  the  same  as  for  the
  3085.      TsrFlags parameter  to TsDoInit().   Please note that the NewStatus
  3086.      parameter  will   OVERRIDE  the   existing  status   flags;  it  is
  3087.      recommended that  the user  call TsGetStat() prior to this call and
  3088.      only make the necessary changes to the status word.
  3089.  
  3090.   Parameters:
  3091.      TsrIdNum.................Identification Number of TSR to call
  3092.      NewStatus................New status WORD for specified TSR
  3093.  
  3094.   Returns:
  3095.      Non-Zero -- Unable to set status word -- invalid ID Number
  3096.      Zero -- Success
  3097.  
  3098.   C Language Usage:
  3099.   
  3100.   extern unsigned far pascal TsSetStat(
  3101.      unsigned short TsrIdNum,
  3102.      unsigned short NewStatus
  3103.      );
  3104.  
  3105.   Pascal Usage:
  3106.   
  3107.   function TsSetStat(
  3108.      TsrIdNum  : word
  3109.      NewStatus : word
  3110.      ) : word;
  3111.  
  3112.   Assembler Usage:
  3113.   
  3114.      mov   ax,5453h
  3115.      mov   bx,15h
  3116.      mov   cx,TsrIdNum
  3117.      mov   dx,NewStatus
  3118.      int   2fh
  3119.   ;
  3120.   ;  return code  returned in AX
  3121.   ;
  3122.  
  3123.  
  3124.  
  3125.  
  3126.  
  3127.  
  3128.  
  3129.  
  3130.  
  3131.  
  3132.  
  3133.     Copyright (c) 1988, TesSeRact Development Team, All Rights Reserved
  3134.  
  3135.  
  3136. Page 48                             TesSeRact(TM) Documentation (Ver. 1.00)
  3137.  
  3138.  
  3139. Get Indos State at Popup (Function 16h)
  3140.  
  3141.   This function  is used  to determine  what the state of DOS was at the
  3142.      time of the popup.  Under some conditions, certain things cannot be
  3143.      done while  INDOS is 1 (like SHELLing to a new copy of COMMAND.COM)
  3144.      but are  perfectly valid  when INDOS  is 0.   The value returned by
  3145.      this  routine   is  only   valid  when   called  during  TsrMain(),
  3146.      TsrBackCheck(), or  TsrBackProc() procedures.   Also  note that the
  3147.      value returned  here is  the same  as the  PopupType member  of the
  3148.      TsrData structure.
  3149.  
  3150.   Parameters:
  3151.      TsrIdNum.................Identification Number of TSR to call
  3152.  
  3153.   Returns:
  3154.      FFFFh - invalid TSR ID Code
  3155.      Any other value is current status flags
  3156.  
  3157.   C Language Usage:
  3158.   
  3159.   extern unsigned far pascal TsGetPopType(
  3160.      unsigned short TsrIdNum
  3161.      );
  3162.  
  3163.   Pascal Usage:
  3164.   
  3165.   function TsGetPopType(
  3166.      TsrIdNum : word
  3167.      ) : word;
  3168.  
  3169.   Assembler Usage:
  3170.      mov   ax,5453h
  3171.      mov   bx,16h
  3172.      mov   cx,TsrIdNum
  3173.      int   2fh
  3174.      or    ax,ax
  3175.      jnz   invalid_idnum
  3176.   ;
  3177.   ;  result returned in BX
  3178.   ;
  3179.  
  3180.  
  3181.  
  3182.  
  3183.  
  3184.  
  3185.  
  3186.  
  3187.  
  3188.  
  3189.  
  3190.  
  3191.     Copyright (c) 1988, TesSeRact Development Team, All Rights Reserved
  3192.  
  3193.  
  3194. TesSeRact(TM) Documentation (Ver. 1.00)                             Page 49
  3195.  
  3196.  
  3197.                            TSR Utility Routines
  3198.  
  3199.  
  3200.  
  3201. This group  of TesSeRact  Multiplex Functions was designed specifically for
  3202. communication and  action of  resident programs.    With  this  release  of
  3203. TesSeRact, there  are only  two functions  in this  category --  Call  User
  3204. Procedure and Stuff Keyboard.
  3205.  
  3206.  
  3207.  
  3208.  
  3209.  
  3210.  
  3211.  
  3212.  
  3213.  
  3214.  
  3215.  
  3216.  
  3217.  
  3218.  
  3219.  
  3220.  
  3221.  
  3222.  
  3223.  
  3224.  
  3225.  
  3226.  
  3227.  
  3228.  
  3229.  
  3230.  
  3231.  
  3232.  
  3233.  
  3234.  
  3235.  
  3236.  
  3237.  
  3238.  
  3239.  
  3240.  
  3241.  
  3242.  
  3243.  
  3244.  
  3245.  
  3246.  
  3247.  
  3248.  
  3249.     Copyright (c) 1988, TesSeRact Development Team, All Rights Reserved
  3250.  
  3251.  
  3252. Page 50                             TesSeRact(TM) Documentation (Ver. 1.00)
  3253.  
  3254.  
  3255. Call User Procedure (Function 20h)
  3256.  
  3257.   This function  is designed  to allow  an external  application  (or  a
  3258.      second invocation of the application) to call into the primary TSR.
  3259.      This should  generally be  used to change status, such as turning a
  3260.      feature on or off, adding files to a print queue, etc.  The UserPtr
  3261.      parameter is  passed to the TsrUserProc() function of the specified
  3262.      TSR.  No specifications or recommendations are made as to what this
  3263.      pointer should reference.
  3264.  
  3265.   Parameters:
  3266.      TsrIdNum.................Identification Number of TSR to call
  3267.      UserPtr..................User-defined, FAR pointer to ANYTHING
  3268.  
  3269.   Returns:
  3270.      Non-Zero -- Unable to pass pointer -- invalid ID Number
  3271.      Zero -- Success
  3272.  
  3273.   C Language Usage:
  3274.   
  3275.   extern unsigned far pascal TsCallUserProc(
  3276.      unsigned short TsrIdNum,
  3277.      void far *UserPtr
  3278.      );
  3279.  
  3280.   Pascal Usage:
  3281.   
  3282.   function TsCallUserProc(
  3283.      TsrIdNum : word;
  3284.      UserPtr  : pointer
  3285.      ) : word;
  3286.  
  3287.   Assembler Usage:
  3288.   
  3289.      mov   ax,5453h
  3290.      mov   bx,20h
  3291.      mov   cx,TsrIdNum
  3292.      les   di,UserPtr
  3293.      int   2fh
  3294.   ;
  3295.   ;  result returned in AX
  3296.   ;
  3297.  
  3298.  
  3299.  
  3300.  
  3301.  
  3302.  
  3303.  
  3304.  
  3305.  
  3306.  
  3307.     Copyright (c) 1988, TesSeRact Development Team, All Rights Reserved
  3308.  
  3309.  
  3310. TesSeRact(TM) Documentation (Ver. 1.00)                             Page 51
  3311.  
  3312.  
  3313. Stuff Keyboard (Function 21h)
  3314.  
  3315.   This function  allows an  application to  'stuff' keystrokes  into the
  3316.      BIOS keyboard buffer.  If the high byte of the 'Speed' parameter is
  3317.      zero, both  ASCII code and SCAN code must be provided in the buffer
  3318.      passed to  this function.   The  correct sequence  is 'ASCII  code'
  3319.      followed by  'scan code.'   If the high byte of the Speed parameter
  3320.      is NON-ZERO,  then only  the ASCII  code is needed -- the TesSeRact
  3321.      routines will  automatically place a '0' in the buffer for the scan
  3322.      code (except  for a  <RETURN> --  for which  the routines place the
  3323.      correct scan  code of '1Ch' in the buffer).  If there is not enough
  3324.      room in  the internal 80-character (160-byte) buffer for the entire
  3325.      buffer being  passed, NONE  of the characters are stuffed.  If this
  3326.      function returns the value 'F0F0 (hex),' it signifies that the user
  3327.      pressed Control-C  or Control-Break  and should  do any  processing
  3328.      necessary to  abort a  keyboard stuff.   Note  that the buffer that
  3329.      KbdPtr references is an array of characters; if stuffing scan codes
  3330.      and ASCII  codes, make  sure you reference the two bytes correctly.
  3331.      Also, KbdLen  is NOT  the number  of bytes  in the array; it is the
  3332.      number of characters to stuff!
  3333.  
  3334.   Parameters:
  3335.      TsrIdNum.................Identification Number of TSR to call
  3336.      KbdPtr...................Pointer to buffer to stuff
  3337.      KbdLen...................Number of characters to place in buffer
  3338.      Speed....................0=Slow (only stuff when buffer is empty)
  3339.                               1=Medium (four characters per tick)
  3340.                               2=Fast (up to 15 characters per tick)
  3341.                               If high byte is non-zero, KbdPtr is an
  3342.                               array of ASCII codes; if it is zero,
  3343.                               KbdPtr is an array of ASCII/Scan Code
  3344.                               pairs.
  3345.  
  3346.   Returns:
  3347.      F0F0h -- User aborted paste with ^C or ^Break
  3348.      Non-Zero -- Unable to stuff buffer -- invalid ID Number or buffer full
  3349.      Zero -- Success
  3350.      
  3351.  
  3352.   C Language Usage:
  3353.   
  3354.   extern unsigned far pascal TsStuffKeyboard(
  3355.      unsigned short TsrIdNum,
  3356.      void far *KbdChars,
  3357.      unsigned short CharCount,
  3358.      unsigned short Speed
  3359.      );
  3360.  
  3361.           (continued)
  3362.  
  3363.  
  3364.  
  3365.     Copyright (c) 1988, TesSeRact Development Team, All Rights Reserved
  3366.  
  3367.  
  3368. Page 52                             TesSeRact(TM) Documentation (Ver. 1.00)
  3369.  
  3370.  
  3371.   Pascal Usage:
  3372.   
  3373.   function TsStuffKeyboard(
  3374.      TsrIdNum : word;
  3375.      KbdPtr   : pointer;
  3376.      KbdLen   : word;
  3377.      Speed    : word
  3378.      ) : word;
  3379.  
  3380.   Assembler Usage:
  3381.   
  3382.      mov   ax,5453h
  3383.      mov   bx,21h
  3384.      mov   cx,TsrIdNum
  3385.      les   di,KbdPtr
  3386.      mov   si,KbdLen
  3387.      mov   dx,Speed
  3388.      int   2fh
  3389.   ;
  3390.   ;  result returned in AX
  3391.   ;
  3392.  
  3393.  
  3394.  
  3395.  
  3396.  
  3397.  
  3398.  
  3399.  
  3400.  
  3401.  
  3402.  
  3403.  
  3404.  
  3405.  
  3406.  
  3407.  
  3408.  
  3409.  
  3410.  
  3411.  
  3412.  
  3413.  
  3414.  
  3415.  
  3416.  
  3417.  
  3418.  
  3419.  
  3420.  
  3421.  
  3422.  
  3423.     Copyright (c) 1988, TesSeRact Development Team, All Rights Reserved
  3424.  
  3425.  
  3426. TesSeRact(TM) Documentation (Ver. 1.00)                             Page 53
  3427.  
  3428.  
  3429.              Chapter 8.  Writing a TesSeRact TSR -- A Tutorial
  3430.  
  3431. This chapter  is intended  to briefly describe the steps needed to create a
  3432. TesSeRact TSR.   Language-specific  differences are covered in Chapter 9 --
  3433. this chapter serves only as an outline to the general procedure.
  3434.  
  3435. The first  step is  to design your program.  Write it, test it, debug it --
  3436. all without  ever considering  a TSR.   Put your main procedural statements
  3437. OUTSIDE of  the primary  execution loop  [main() for C programmers] -- in a
  3438. separate function, for example.
  3439.  
  3440. Once you've  got the  application debugged, the next step is to set up your
  3441. stack areas.  The stack should be split into two parts, for both background
  3442. and popup  processing.  If you only use one type of processing in your TSR,
  3443. you should  specify a  small (4  bytes, or  so) area  for the  other stack.
  3444. Also, if  you are  using a  high-level language, it is strongly recommended
  3445. that you use a stack that is within the default stack area provided by your
  3446. compiler -- because many functions assume certain things about the stack.
  3447.  
  3448. Now determine  what kind  of TSR  processing you need -- background, popup,
  3449. timer, or  a combination  of the  three.   Also determine if you need to be
  3450. able to  communicate with the resident portion of the program, with a user-
  3451. procedure.
  3452.  
  3453. Define  the   TesSeRact  entry   points:    TsrBackCheck(),  TsrBackProc(),
  3454. TsrTimerProc(), TsrMain(), TsrUserProc() and TsrCleanUp().  Note that users
  3455. of the  assembler version  must define ALL these entry points in their code
  3456. in order to resolve linker references.  High-level language users will find
  3457. dummy procedures provided to handle these references.
  3458.  
  3459. Your primary  loops of  execution should  be placed  in either TsrMain() or
  3460. TsrBackProc().   Small bits of code to test flags or other status should be
  3461. placed  in   TsrBackCheck()  and   TsrTimerProc()  --   and  remember  that
  3462. TsrBackCheck() returns  a flag  that determines  if TsrBackProc()  is to be
  3463. called.
  3464.  
  3465. Now it's  time to  set up  your data  structures.  Variables for hotkey and
  3466. shift state values should be set up so that they can be easily changed.  An
  3467. eight-byte array  of characters  should be  defined, which will become your
  3468. TSR Identification  String.  USE EIGHT CHARACTERS!  Pad the string to eight
  3469. bytes if needed, because the TesSeRact routines check all eight bytes for a
  3470. match.   Also  define  a  data  area  that  will  be  used  to  store  your
  3471. Identification Number.
  3472.  
  3473. If you  plan to  use multiple  hot keys,  set up an ExtraHot structure that
  3474. contains the  scan code,  shift state  and flag  byte for  each  additional
  3475. hotkey you want.
  3476.  
  3477.  
  3478.  
  3479.  
  3480.  
  3481.     Copyright (c) 1988, TesSeRact Development Team, All Rights Reserved
  3482.  
  3483.  
  3484. Page 54                             TesSeRact(TM) Documentation (Ver. 1.00)
  3485.  
  3486.  
  3487. Next it's  time to  begin adding  the TesSeRact  code to  your program.  As
  3488. early in  execution as  possible, set  up pointers  to your  internal stack
  3489. areas, and  call  TsSetStack().    Next,  call  TsCheckResident(),  passing
  3490. pointers to  your Identification  String and  Identification Number.   This
  3491. routine will  pace the  appropriate identification  number in the data area
  3492. you indicate.   This identification number will be used on all future calls
  3493. to TesSeRact once you call TsDoInit().
  3494.  
  3495. This is  a good place to call TsCheckHotkey() to make sure that another TSR
  3496. is not already using the hotkey combination you want.
  3497.  
  3498. Finally,  a  call  is  made  to  TsDoInit(),  passing  it  the  appropriate
  3499. parameters as described in the documentation.  The most important parameter
  3500. to this  function is  the resident  size.   Calculating this correctly will
  3501. solve many problems!
  3502.  
  3503. If you're  using multiple  hotkeys, or  need  to  communicate  through  the
  3504. TesSeRact  Multiplex   interface,  the   time  to   do  it  is  inside  the
  3505. initialization portion  of TsrCleanUp().  This function is called AFTER the
  3506. TesSeRact interrupts  have been  installed.  In my TSRs, I generally do all
  3507. my initialization  (except for  memory  allocation)  inside  this  routine.
  3508. Please note  that it is not possible to call a TesSeRact Multiplex Function
  3509. before TsrCleanUp() is called.  The Multiplex routines are dependent on the
  3510. interrupt handler being installed.
  3511.  
  3512. And that's  all there is to it!  Of course, there are many other things you
  3513. can do  -- for  example, if  when you call TsCheckResident(), you determine
  3514. that your  program is  already resident,  you can do a variety of things --
  3515. pass new  parameters to the resident portion using TsrUserProc(), etc.  You
  3516. can modify the hotkeys, status, or anything as needed.
  3517.  
  3518. For more  specific examples  of this,  see Chapter  9 for language-specific
  3519. details, and also see the demonstration programs.
  3520.  
  3521.  
  3522.  
  3523.  
  3524.  
  3525.  
  3526.  
  3527.  
  3528.  
  3529.  
  3530.  
  3531.  
  3532.  
  3533.  
  3534.  
  3535.  
  3536.  
  3537.  
  3538.  
  3539.     Copyright (c) 1988, TesSeRact Development Team, All Rights Reserved
  3540.  
  3541.  
  3542. TesSeRact(TM) Documentation (Ver. 1.00)                             Page 55
  3543.  
  3544.  
  3545.                       Chapter 9.  Language Specifics
  3546.  
  3547. This chapter  is designed to explain how to compile/assemble/link your Ram-
  3548. Resident programs  with the appropriate version of TesSeRact.  It also will
  3549. describe any language-specific variables or procedures that must be called.
  3550. A close  study of the demonstration code would be useful while reading this
  3551. chapter.
  3552.  
  3553.  
  3554.                                   Turbo C
  3555.  
  3556. Writing a  TSR with  Turbo C is very straightforward.  Remembering that the
  3557. stack is  ABOVE the  heap in  tiny and  small models,  developers can use a
  3558. routine such  as the  SizeOfCode() module  provided  in  the  demonstration
  3559. program.   This routine allows developers to determine how much of the heap
  3560. and stack  the developer wants to be resident.  If you specify ALLSTACK, it
  3561. is absolutely  possible to  use Turbo-C's  normal dynamic memory allocation
  3562. routines (malloc,  free, etc.)  in tiny  or small  model  (farmalloc()  and
  3563. dynamic memory  under other memory models is a different subject entirely).
  3564. Developers should set the size of the heap and stack they desire by setting
  3565. _heaplen and _stklen to appropriate values.
  3566.  
  3567. The Turbo  C demonstration  program was compiled with the following command
  3568. line:
  3569.   
  3570.   TCC -C -M -w -K -O -Z -k -d TESSDEMO
  3571.   tlink /m /l /s /c c0s+tessdemo,tessdemo,tessdemo,tess+cs
  3572.  
  3573. One  other   item  of  consideration  for  TC  is  the  need  to  call  the
  3574. _restorezero() function from the termination portion of TsrCleanUp().  This
  3575. is needed  to restore the Interrupt 0 vector to its former position.  Other
  3576. packages or  library routines  may install  their own termination handlers;
  3577. please note that at present, TC 1.5 does not provide a mechanism for easily
  3578. detecting their  presence, other  than by  actually searching and modifying
  3579. the _atexit() chain.
  3580.  
  3581.  
  3582.  
  3583.  
  3584.  
  3585.  
  3586.  
  3587.  
  3588.  
  3589.  
  3590.  
  3591.  
  3592.  
  3593.  
  3594.  
  3595.  
  3596.  
  3597.     Copyright (c) 1988, TesSeRact Development Team, All Rights Reserved
  3598.  
  3599.  
  3600. Page 56                             TesSeRact(TM) Documentation (Ver. 1.00)
  3601.  
  3602.  
  3603.                                 Microsoft C
  3604.  
  3605. From a functional standpoint, the only difference between using Microsoft C
  3606. for a  TSR as opposed to Turbo C is that instead of calling _restorezero(),
  3607. you instead  call _ctermsub().   Note  that this  function  DOES  call  all
  3608. procedures in  the _atexit() chain, safely unlinking anyone who needs to be
  3609. unlinked.   Also, since the stack is BELOW the heap in MSC small and medium
  3610. models, using  dynamic memory allocation functions is a chancy thing, since
  3611. the RUN-TIME  LIBRARY code  has no  way  of  knowing  that  you've  put  an
  3612. arbitrary limit on the size of the heap.
  3613.  
  3614. TESSDEMO may be compiled with MSC using the following command lines:
  3615.   
  3616.   CL /W3 /Ox /DMSC5 TESSDEMO.C
  3617.  
  3618. By defining the variable MSC5, routines are compiled that are provided with
  3619. the Turbo C RUNTIME LIBRARY, allowing the program to run.
  3620.  
  3621. Some problems  have been  noted concerning  the console  I/O  functions  of
  3622. Microsoft C  version 5.0  and 5.1.   We  are currently  unclear as  to what
  3623. exactly the  problems are,  but we  recommend you  do not  use cputs()  and
  3624. cprintf() from  inside your TSR.  Note that the problem is not due to a DOS
  3625. reentrancy problem  -- because making the DOS function calls directly works
  3626. just fine.
  3627.  
  3628. Another thing  to be  aware of  is that  many MSC  functions call  malloc()
  3629. without being  documented to  do so  -- printf()  is one in particular.  Be
  3630. careful about your heap management with MSC.
  3631.  
  3632. Finally, note that the size of the stack under MSC may be controlled either
  3633. by  using  the  EXEMOD  program  and  directly  modifying  the  EXE  header
  3634. information, or by using the /STACK parameter at the link step.
  3635.  
  3636.  
  3637.  
  3638.  
  3639.  
  3640.  
  3641.  
  3642.  
  3643.  
  3644.  
  3645.  
  3646.  
  3647.  
  3648.  
  3649.  
  3650.  
  3651.  
  3652.  
  3653.  
  3654.  
  3655.     Copyright (c) 1988, TesSeRact Development Team, All Rights Reserved
  3656.  
  3657.  
  3658. TesSeRact(TM) Documentation (Ver. 1.00)                             Page 57
  3659.  
  3660.  
  3661.                                Turbo Pascal
  3662.  
  3663. To use TesSeRact with Turbo Pascal 4.0, you need simply add the line:
  3664.   
  3665.   Uses TESSTP;
  3666.  
  3667. to your  program.   The various  function, procedure and CONST declarations
  3668. are located in the TESS.TP4 file.
  3669.  
  3670. Please note  that when  using TP4,  there is  one additional procedure that
  3671. MUST be  called before ANY of the other TesSeRact routines.  Because of the
  3672. organization of  TP4 units,  it is  not possible  to have  code in the unit
  3673. directly call  routines in  the main  section of  the code.   To get around
  3674. this, the  TP Unit has been written with indirect calls to these locations,
  3675. which are  initialized to  FAR RETURNS.   In  order to  set the appropriate
  3676. addresses into  these data  locations, TP4  users must call the TsSetAdrTP4
  3677. procedure, described below:
  3678.   
  3679.   
  3680.   procedure TsSetAdrTP4(
  3681.       ProcAdr : pointer;
  3682.       Index : integer
  3683.       );
  3684.  
  3685.   This procedure  exists only  in the TP4 version; it is used to set the
  3686.      TesSeRact pointers  to permit  popup of  your own  routines. During
  3687.      initialization of  the unit,  all six pointers are set to a FAR RET
  3688.      within the  unit; your  code must  reset those you want to use, via
  3689.      "TsSetAdrTP4( @TsrMain, 2 );" etc.  The index codes to use are:
  3690.           0 = TsrTimerProc
  3691.           1 = TsrBackProc
  3692.           2 = TsrMain
  3693.           3 = TsrBackCheck
  3694.           4 = TsrUserProc
  3695.           5 = TsrCleanUp
  3696.  
  3697.  
  3698.  
  3699.  
  3700.  
  3701.  
  3702.  
  3703.  
  3704.  
  3705.  
  3706.  
  3707.  
  3708.  
  3709.  
  3710.  
  3711.  
  3712.  
  3713.     Copyright (c) 1988, TesSeRact Development Team, All Rights Reserved
  3714.  
  3715.  
  3716. Page 58                             TesSeRact(TM) Documentation (Ver. 1.00)
  3717.  
  3718.  
  3719.                                  Assembler
  3720.  
  3721. Writing a  TesSeRact  program  using  the  assembler  version  affords  the
  3722. programmer the  most compact code (because NEAR calls are used, rather than
  3723. FAR), as  well as  the most  flexibility.   The TesSeRact  routines in this
  3724. version ASSUME that CS=DS, and any function that references the DI register
  3725. also assumes  that ES=CS.   This  version will  ONLY  work  for  .COM-style
  3726. programs.   It is  not, however,  necessary for  the developer  to use  the
  3727. following common code sequence:
  3728.   
  3729.      ORG 100h
  3730.   start:
  3731.      jmp begin
  3732.      .....
  3733.      END START
  3734.  
  3735. because the TesSeRact library already has the code embedded within it.  The
  3736. program must  have a  PUBLIC variable  called TESSINITSTART.  The TesSeRact
  3737. Library gets control of the program and does a NEAR JMP to that label.  All
  3738. registers that  are normally  in effect  at the beginning of a .COM program
  3739. are still as they were.
  3740.  
  3741. Other than  this label, there are some minor differences in calling some of
  3742. the TesSeRact  Library Routines;  most notably, TsDoInit() takes the OFFSET
  3743. of the  top of  memory, as  is the  common practice  for .COM  programs, as
  3744. opposed to the number of paragraphs of RAM required.  The TsDoInit() module
  3745. will convert to paragraphs.
  3746.  
  3747. Please note also that ALL the entry points MUST exist in the code.  See the
  3748. example program for more details.
  3749.  
  3750. The TESSPARK  demonstration program  was assembled/linked using SLR Systems
  3751. OPTASM  1.0,   and  Borland  International's  TLINK  1.1  as  noted  below.
  3752. Microsoft's MASM and LINK utilities work just as well.
  3753.   
  3754.   OPTASM /Mx tesspark;
  3755.   TLINK /M /L /S /C tess_asm+tess_bp+tesspark+tess_end,tesspark;
  3756.  
  3757. The functions  located in  TESS_END.OBJ are  not  used  after  the  TSR  is
  3758. initialized and should therefore be placed in the .EXE file past the end of
  3759. the resident  portion of  your program.  TESS_BP.OBJ has been provided as a
  3760. separate module to allow ease in replacing it with your own BEEP routine.
  3761.  
  3762.  
  3763.  
  3764.  
  3765.  
  3766.  
  3767.  
  3768.  
  3769.  
  3770.  
  3771.     Copyright (c) 1988, TesSeRact Development Team, All Rights Reserved
  3772.  
  3773.  
  3774. TesSeRact(TM) Documentation (Ver. 1.00)                             Page 59
  3775.  
  3776.  
  3777.                Chapter 10.  Communicating with the TesSeRact
  3778.  
  3779. NOTE:   This chapter,  with the following copyright notice and attribution,
  3780. may be  included with  any/all products  using  the  TesSeRact  Library  or
  3781. supporting the TesSeRact Standard for Ram-Resident Program Communication.
  3782.   
  3783.   Copyright 1988, TesSeRact Development Team
  3784.   All Rights Reserved
  3785.   
  3786.   By Chip Rabinowitz and Jim Kyle
  3787.   
  3788.  
  3789. In order for a program to communicate with routines which use the TesSeRact
  3790. Standard, it MUST make use of the TesSeRact Multiplex Functions.
  3791.  
  3792. The TesSeRact Standard for Ram-Resident Program Communication is a group of
  3793. functions, latched  onto DOS' own Interrupt 2Fh (Multiplex).  DOS uses this
  3794. interrupt  to   communicate  with  its  own  TSRs  (PRINT.COM,  ASSIGN.COM,
  3795. SHARE.COM), and  the TesSeRact  Development Team felt it was appropriate to
  3796. service TSR  programs using  the same  interface.   These functions are all
  3797. accessed by generating an Interrupt 2Fh, with AX=5453 (hex).
  3798.  
  3799. Important!   In versions  of MS-DOS  and PC-DOS prior to 3.0, the Interrupt
  3800. 2Fh vector  was initialized  to zero rather than being pointed into the DOS
  3801. service area.  With such DOS versions, a program calling Interrupt 2Fh will
  3802. cause the  machine to  crash if  a  TesSeRact  TSR  has  not  been  loaded.
  3803. TsVerify2F() should  be called  prior to  calling  this  function,  or  the
  3804. application should make its own check for the validity of Interrupt 2Fh.
  3805.  
  3806. To determine whether any routine is, in fact, using the TesSeRact Standard,
  3807. use Multiplex  Function 00h  (Check Install).    Check  Install  determines
  3808. whether a TesSeRact program has been loaded.  It is called in the following
  3809. fashion (the  assembler interface  is required  if the TesSeRact Library is
  3810. not available.   If  it is, refer to the section on the Multiplex functions
  3811. for details of its use in high level languages):
  3812.   
  3813.     mov    ax,5453h                ;the TesSeRact Multiplex signature
  3814.     mov    si,offset IDStr         ;FAR pointer to 8-character name of
  3815.     mov    ds,seg IDStr            ; routine being checked for
  3816.     xor    cx,cx                   ;will count TesSeRact using CX
  3817.     xor    bx,bx                   ;specify Function 00h
  3818.     int    2fh
  3819.  
  3820. IDStr is  an eight-byte  data area  that contains  the  TSR  Identification
  3821. String unique  to  the  particular  TSR  program.    All  eight  bytes  are
  3822. significant when comparing strings, so make sure you specify the values for
  3823. ALL eight  bytes.   If necessary,  pad an IDStr array with spaces to ensure
  3824. eight unique bytes.
  3825.  
  3826.  
  3827.  
  3828.     Copyright (c) 1988, TesSeRact Development Team, All Rights Reserved
  3829.  
  3830.  
  3831. Page 60                             TesSeRact(TM) Documentation (Ver. 1.00)
  3832.  
  3833.  
  3834. If no TesSeRact routine is present in the system, the interrupt will return
  3835. with the  signature in  the AX  register unchanged.   If  the routine being
  3836. sought is present, AX will contain 0FFFFh, and the CX register will contain
  3837. its Identification  Number.   This ID  Number is  used by all the remaining
  3838. TesSeRact Multiplex  Functions, rather than the full Identification String,
  3839. and should be saved for use.
  3840.  
  3841. Note that Check Install will ALWAYS return an Identification Number for the
  3842. routine being  sought if  ANY TesSeRact  TSR is  present, even  though  the
  3843. routine may  not yet  be present  in the system.  The second step in making
  3844. certain that  the routine  is, in  fact, present is to request a pointer to
  3845. its data area.
  3846.  
  3847. Check Install  does no  initialization of  internal  data  structures,  and
  3848. should ONLY  be used  by a  program to  FIND a  TSR in  memory and get it's
  3849. handle -- NOT to determine if a TSR has already been loaded.
  3850.  
  3851. In the  TesSeRact Standard, Multiplex Function 01h returns a FAR pointer to
  3852. a  data   area  that   contains  the  TsrParms  pointer  --  including  the
  3853. Identification String,  Identification Number, and FuncFlag members for the
  3854. TSR bearing the IdNum passed into the function.  This function is called as
  3855. follows:
  3856.   
  3857.     mov    ax,5453h
  3858.     mov    bx,01h
  3859.     mov    cx,TsrIdNum
  3860.     int    2fh
  3861.  
  3862. If the  Identification Number  in CX matches the TSR's ID Number (which was
  3863. returned by Multiplex Function 00h), the TSR returns with ES:BX pointing to
  3864. the TsrParms  area and AX equal to zero.  Any other value in AX upon return
  3865. indicates that the TSR could not be located.
  3866.  
  3867. Once the  pointer to  the User  Parameter Area  is obtained,  most  of  the
  3868. critical information  used by  the routine  is  available  to  the  calling
  3869. program.
  3870.  
  3871. Other  TesSeRact  Multiplex  Functions  may  be  accessed  by  calling  the
  3872. appropriate Interrupt  2Fh Multiplex  function call,  as  described  below.
  3873. Please  note  that  these  are  narrative  descriptions  of  the  Multiplex
  3874. functions only  -- complete  descriptions are  available in  the  TesSeRact
  3875. Documentation.
  3876.  
  3877.  
  3878.  
  3879.  
  3880.  
  3881.  
  3882.  
  3883.  
  3884.  
  3885.  
  3886.     Copyright (c) 1988, TesSeRact Development Team, All Rights Reserved
  3887.  
  3888.  
  3889. TesSeRact(TM) Documentation (Ver. 1.00)                             Page 61
  3890.  
  3891.  
  3892.                                      
  3893.                        Check Install (Function 00h)
  3894.  
  3895.   This function  must be  called before TsDoInit().  It checks to see if
  3896.      this TSR has already been loaded by comparing the passed IDStr with
  3897.      other compatible  TSRs.    The  primary  difference  between  Check
  3898.      Install  and  TsCheckResident()  is  that  Check  Install  does  no
  3899.      initialization of internal data structures, and should ONLY be used
  3900.      by a  program to  FIND a TSR in memory and get its handle -- NOT to
  3901.      determine if  the TSR  you are  trying to  install has already been
  3902.      loaded.  Please note that under DOS versions 2.x, the Interrupt 2Fh
  3903.      vector is  initialized to  ZERO --  a program calling Interrupt 2Fh
  3904.      will cause  the machine  to crash  if a  TesSeRact TSR has not been
  3905.      loaded.   TsVerify2F() should  be  called  prior  to  calling  this
  3906.      function, or  the application  should make  its own  check for  the
  3907.      validity of Interrupt 2Fh.
  3908.                                      
  3909.                Return User Parameter Pointer (Function 01h)
  3910.  
  3911.   This function  returns a  pointer to  the  specified  TSR's  parameter
  3912.      block.   This block  contains important  information about the TSR.
  3913.      The structure  is described in detail in Chapter 4 of the TesSeRact
  3914.      Documentation as the TsrParms structure.  Note that other TesSeRact
  3915.      Multiplex Functions provide information that is also available from
  3916.      the data  contained in this structure; they are designed to be used
  3917.      as an alternative method for getting information about the TSR.
  3918.                                      
  3919.                         Check Hotkey (Function 02h)
  3920.  
  3921.   This function  is used  to determine  if the selected hotkey is not in
  3922.      use by  any other  TesSeRact-compatible  TSR.    At  present,  this
  3923.      function checks  only for  PRIMARY Hotkeys and does not compare the
  3924.      'shift state'  required for  activation, assuming  that a  TSR that
  3925.      uses ATL-T to pop up would conflict with a TSR that uses Shift-Alt-
  3926.      T.
  3927.                                      
  3928.            Replace Default Interrupt 24h Handler (Function 03h)
  3929.  
  3930.   This function  is used to replace the TesSeRact default Critical Error
  3931.      Handler routine.   The default procedure returns a FAIL code to the
  3932.      calling program.  This routine allows the developer to replace that
  3933.      function with  his own.  Registers on entry to this routine are the
  3934.      same as  described in  the DOS  Technical Reference Manual, and all
  3935.      conditions described  there are  in effect.   Once control has been
  3936.      passed to  this routine,  it is  the developer's  responsibility to
  3937.      return back  to DOS  or the calling program.  Please note that this
  3938.      routine, if  implemented by  the developer,  cannot be called until
  3939.      the TSR  has been  enabled by  TsDoInit();   this should  be called
  3940.      during the initialization phase of TsrCleanup().
  3941.  
  3942.  
  3943.  
  3944.     Copyright (c) 1988, TesSeRact Development Team, All Rights Reserved
  3945.  
  3946.  
  3947. Page 62                             TesSeRact(TM) Documentation (Ver. 1.00)
  3948.  
  3949.  
  3950.                                      
  3951.                Return TesSeRact Data Pointer (Function 04h)
  3952.  
  3953.   This function  returns a  pointer to the specified TSR's internal data
  3954.      areas.   This block  contains internal  information about  the TSR.
  3955.      The structure  is described  in detail  in Chapter 4 as the TsrData
  3956.      structure.   Note that  other TesSeRact Multiplex Functions provide
  3957.      information that  is also available from the data contained in this
  3958.      structure; they  are designed  to be  used as an alternative method
  3959.      for getting information about the TSR.
  3960.                                      
  3961.                    Set Multiple Hot Keys (Function 05h)
  3962.  
  3963.   This function  is used  to set  multiple  hotkeys  for  a  TSR.    The
  3964.      TsDoInit() function  only has facilities for a single HotKey/Shift-
  3965.      State  combination,  which  should  suffice  for  the  majority  of
  3966.      resident programs.   However,  many programmers want the ability to
  3967.      set up  multiple hotkeys.    Please  note  that  this  routine,  if
  3968.      implemented by  the developer,  cannot be  called until the TSR has
  3969.      been enabled  by TsDoInit();   this  should be  called  during  the
  3970.      initialization phase of TsrCleanup().
  3971.                                      
  3972.                          Enable TSR (Function 10h)
  3973.  
  3974.   This function  calls the  TesSeRact Multiplex interrupt to turn on the
  3975.      'enable' flag  for a  TSR.   It is  the functional  opposite of the
  3976.      TsDisable() function.
  3977.                                      
  3978.                         Disable TSR (Function 11h)
  3979.  
  3980.   This function turns  off the 'enable' flag for a TSR.  The TSR remains
  3981.      in memory,  but it  cannot pop  up,  nor  will  any  of  its  other
  3982.      operations be  active.   As soon as it is enabled again, actions on
  3983.      'hold' (like  keys stuffed  into the  buffer) will immediately take
  3984.      place.  It is the functional opposite of the TsEnable() function.
  3985.                                      
  3986.                     Release TSR [unload] (Function 12h)
  3987.  
  3988.   This function  allows for  releasing a TSR from memory at the earliest
  3989.      possible moment.   In  order for a TSR to remove itself, it must be
  3990.      the last  interrupt in  the interrupt  chain for every interrupt it
  3991.      uses.   If another  program is  loaded  that  interferes  with  the
  3992.      interrupt chain,  the TesSeRact  Library will wait until it is safe
  3993.      to remove your TSR from RAM.
  3994.  
  3995.  
  3996.  
  3997.  
  3998.  
  3999.  
  4000.  
  4001.  
  4002.     Copyright (c) 1988, TesSeRact Development Team, All Rights Reserved
  4003.  
  4004.  
  4005. TesSeRact(TM) Documentation (Ver. 1.00)                             Page 63
  4006.  
  4007.  
  4008.                                      
  4009.                         Restart TSR (Function 13h)
  4010.  
  4011.   This function is used to 'restart' a TSR that has been released but is
  4012.      still physically  in memory.   Note that TsrCleanUp() is NOT called
  4013.      again for  initialization,  because  the  program  has  never  been
  4014.      notified through the same routine that it was removed.
  4015.                                      
  4016.                     Get TSR Status Word (Function 14h)
  4017.  
  4018.   This function  is used  to determine what the current status flags are
  4019.      for the specified TSR.  The possible values are the same as for the
  4020.      TsrFlags parameter  to TsDoInit().  Note also that this status word
  4021.      may also  be accessed directly by modifying the TsrStatus word from
  4022.      the TsrParms  Data Structure.   The  high-level language  functions
  4023.      specifically return  the status  flags if  no error  occurred;  the
  4024.      assembler version is atypical in that this value is not returned in
  4025.      AX, as expected.
  4026.                                      
  4027.                     Set TSR Status Word (Function 15h)
  4028.  
  4029.   This function  is used  to modify  the existing  status flags  for the
  4030.      specified TSR.   The  possible values  are  the  same  as  for  the
  4031.      TsrFlags parameter  to TsDoInit().   Please note that the NewStatus
  4032.      parameter  will   OVERRIDE  the   existing  status   flags;  it  is
  4033.      recommended that  the user  call TsGetStat() prior to this call and
  4034.      only make the necessary changes to the status word.
  4035.                                      
  4036.                   Get Indos State at Popup (Function 16h)
  4037.  
  4038.   This function  is used  to determine  what the state of DOS was at the
  4039.      time of the popup.  Under some conditions, certain things cannot be
  4040.      done while  INDOS is 1 (like SHELLing to a new copy of COMMAND.COM)
  4041.      but are  perfectly valid  when INDOS  is 0.   The value returned by
  4042.      this  routine   is  only   valid  when   called  during  TsrMain(),
  4043.      TsrBackCheck(), or  TsrBackProc() procedures.   Also  note that the
  4044.      value returned  here is  the same  as the  PopupType member  of the
  4045.      TsrData structure.
  4046.                                      
  4047.                        Stuff Keyboard (Function 21h)
  4048.  
  4049.   This function  is designed  to allow  an external  application  (or  a
  4050.      second invocation of the application) to call into the primary TSR.
  4051.      This should  generally be  used to change status, such as turning a
  4052.      feature on or off, adding files to a print queue, etc.  The UserPtr
  4053.      parameter is  passed to the TsrUserProc() function of the specified
  4054.      TSR.  No specifications or recommendations are made as to what this
  4055.      pointer should reference.
  4056.  
  4057.  
  4058.  
  4059.  
  4060.     Copyright (c) 1988, TesSeRact Development Team, All Rights Reserved
  4061.  
  4062.  
  4063. Page 64                             TesSeRact(TM) Documentation (Ver. 1.00)
  4064.  
  4065.  
  4066.                                      
  4067.                     Call User Procedure (Function 20h)
  4068.  
  4069.   This function  allows an  application to  'stuff' keystrokes  into the
  4070.      BIOS keyboard buffer.  If the high byte of the 'Speed' parameter is
  4071.      zero, both  ASCII code and SCAN code must be provided in the buffer
  4072.      passed to  this function.   The  correct sequence  is 'ASCII  code'
  4073.      followed by  'scan code.'   If the high byte of the Speed parameter
  4074.      is NON-ZERO,  then only  the ASCII  code is needed -- the TesSeRact
  4075.      routines will  automatically place a '0' in the buffer for the scan
  4076.      code (except  for a  <RETURN> --  for which  the routines place the
  4077.      correct scan  code of '1Ch' in the buffer).  If there is not enough
  4078.      room in  the internal 80-character (160-byte) buffer for the entire
  4079.      buffer being  passed, NONE  of the characters are stuffed.  If this
  4080.      function returns the value 'F0F0 (hex),' it signifies that the user
  4081.      pressed Control-C  or Control-Break  and should  do any  processing
  4082.      necessary to  abort a  keyboard stuff.   Note  that the buffer that
  4083.      KbdPtr references is an array of characters; if stuffing scan codes
  4084.      and ASCII  codes, make  sure you reference the two bytes correctly.
  4085.      Also, KbdLen  is NOT  the number  of bytes  in the array; it is the
  4086.      number of characters to stuff!
  4087.  
  4088.  
  4089.  
  4090. Any developer  wishing a  copy of the source code for TesSeRact's Interrupt
  4091. 2Fh Multiplex  Handler may  receive it by sending a self-addressed, stamped
  4092. envelope to:
  4093.   
  4094.           TesSeRact Development Team
  4095.           c/o Chip Rabinowitz
  4096.           2084 Woodlawn Avenue
  4097.           Glenside, PA 19038
  4098.  
  4099. For more  information contact  the TesSeRact  Development Team at the above
  4100. address, or at Compuserve 70731,20, or MCIMAIL 315-5415 (TESSERACT).
  4101.  
  4102.  
  4103.  
  4104.  
  4105.  
  4106.  
  4107.  
  4108.  
  4109.  
  4110.  
  4111.  
  4112.  
  4113.  
  4114.  
  4115.  
  4116.  
  4117.  
  4118.     Copyright (c) 1988, TesSeRact Development Team, All Rights Reserved
  4119.  
  4120.  
  4121. TesSeRact(TM) Documentation (Ver. 1.00)                             Page 65
  4122.  
  4123.  
  4124.             Chapter 11.  Writing TesSeRact-Compatible Programs
  4125.  
  4126. NOTE:   This chapter,  with the following copyright notice and attribution,
  4127. may be  included with  any/all products  using  the  TesSeRact  Library  or
  4128. supporting the TesSeRact Standard for Ram-Resident Program Communication.
  4129.   
  4130.   Copyright 1988, TesSeRact Development Team
  4131.   All Rights Reserved
  4132.   
  4133.   By Chip Rabinowitz and Jim Kyle
  4134.   
  4135.  
  4136. The TesSeRact  Development Team  was organized  in early  1986 for the sole
  4137. purpose of  establishing a  standard to be shared by TSR program developers
  4138. in the  hopes of  reducing the  notorious levels  of conflicts between such
  4139. programs.   The members  of the  Development Team represented a majority of
  4140. the leading independent TSR developers.
  4141.  
  4142. At first,  the Team  planned on  developing  a  full  Applications  Program
  4143. Interface  for   use  by   both  independent   and   commercial   programs.
  4144. Unfortunately, the  team was  unable to  get strong enough support from the
  4145. commercial TSR publishing houses and this idea went by the wayside.
  4146.  
  4147. The current  TesSeRact product  consists of both a Library of routines that
  4148. enable developers  to write  safe Ram-Resident  programs, and  an interface
  4149. that permits developers to communicate with their own (and other) TSRs.
  4150.  
  4151. The TesSeRact Standard for Ram-Resident Program Communication is a group of
  4152. functions, latched  onto DOS' own Interrupt 2Fh (Multiplex).  DOS uses this
  4153. interrupt  to   communicate  with  its  own  TSRs  (PRINT.COM,  ASSIGN.COM,
  4154. SHARE.COM), and  the TesSeRact  Development Team felt it was appropriate to
  4155. service TSR  programs using  the same  interface.   These functions are all
  4156. accessed by generating an Interrupt 2Fh, with AX=5453 (hex).
  4157.  
  4158. In order  for a  program to support the TesSeRact Standard, it MUST provide
  4159. the following Multiplex Functions:
  4160.   
  4161.   Function 00h (Check Install)
  4162.   Function 01h (Return User Parameter Pointer)
  4163.  
  4164. Check Install is used by TesSeRact programs to determine if the program has
  4165. been loaded before.  It is called in the following fashion:
  4166.   
  4167.   mov     ax,5453h
  4168.   mov     si,offset IDStr
  4169.   mov     ds,seg IDStr
  4170.   xor     cx,cx
  4171.   xor     bx,bx
  4172.   int     2fh
  4173.  
  4174.  
  4175.  
  4176.     Copyright (c) 1988, TesSeRact Development Team, All Rights Reserved
  4177.  
  4178.  
  4179. Page 66                             TesSeRact(TM) Documentation (Ver. 1.00)
  4180.  
  4181.  
  4182. IDStr is  an eight-byte data area that contains a unique TSR Identification
  4183. String.   The Interrupt  2F routine  should compare  the passed  string (as
  4184. shown in  the example  below), with  its own eight-byte string.  If the two
  4185. strings match,  the TSR  should return  with the CX register set to its own
  4186. TSR 'handle' and the AX register set to 0FFFFh.
  4187.  
  4188. If the  identification strings  do not  match, all  the registers should be
  4189. restored, then  the CX  registers should  be INCREMENTED, and the interrupt
  4190. handler should call down the chain.
  4191.  
  4192. Why is it done this way, you may ask?  If every TesSeRact-compatible TSR on
  4193. a particular  system increments  the CX register if there is no match, then
  4194. when the  interrupt procedure  returns to  the caller, the CX register will
  4195. contain the next available handle!
  4196.  
  4197. The following code is taken directly from the TesSeRact Library's Interrupt
  4198. 2Fh handler:
  4199.   
  4200.   finish_2f:
  4201.      add   sp,4                    ;get rid of two words on stack
  4202.      xor   ax,ax                   ;clear AX to show we got it
  4203.   done_2f:
  4204.      iret
  4205.   
  4206.   next_one:
  4207.      inc   cx                      ;try next higher ID code
  4208.   get_out_2f:
  4209.      pop   bx
  4210.      pop   ax
  4211.   not_our_2f:
  4212.      jmp   DPTR [oldint2F]
  4213.   
  4214.   overparms:
  4215.      cmp   ax,5453h                ;ax=5453h for TesSeRact
  4216.      jne   not_our_2f
  4217.      cmp   bx,MAXENT
  4218.      ja    not_our_2f
  4219.      push  ax
  4220.      push  bx
  4221.      or    bx,bx                   ;do check for install first,
  4222.      jz    check_install           ;so we can check ID number only
  4223.                                    ;one time!
  4224.      ....                          ; other code .....
  4225.   
  4226.   check_install:
  4227.                                    ;DS:SI points to ID string
  4228.                                    ;DI contains hotkey for check
  4229.                                    ;CX is current number in chain
  4230.                                    ;   must be 0 from caller
  4231.  
  4232.  
  4233.  
  4234.     Copyright (c) 1988, TesSeRact Development Team, All Rights Reserved
  4235.  
  4236.  
  4237. TesSeRact(TM) Documentation (Ver. 1.00)                             Page 67
  4238.  
  4239.  
  4240.      push  cx
  4241.      push  si                      ;save SI for next one
  4242.      lea   di,[USERPARMS]
  4243.      push  cs
  4244.      pop   es
  4245.      mov   cx,8
  4246.      rep   cmpsb
  4247.      pop   si
  4248.      pop   cx
  4249.      jnz   next_one                ;no match, not us
  4250.      pop   bx
  4251.      pop   ax
  4252.      mov   cx,es:[di]              ;return ID number in CX
  4253.      test  WPTR [STATUS],TSRRELEASED
  4254.      jz    return_idnum
  4255.      or    cx,0ff00h               ;say we're released!
  4256.   return_idnum:
  4257.      xor   ax,ax
  4258.      dec   ax                      ;AX=-1 means already here
  4259.      jmp   short done_2f
  4260.  
  4261. The other  requirement  for  TesSeRact  compatibility  is  to  support  the
  4262. TsrParms data  area (Multiplex  Function  01h).    The  UserParms  area  is
  4263. described as follows:
  4264.   
  4265.   UserParms      db    8 dup (0)
  4266.   IdNum    dw    0            ;TSR Identification Number
  4267.   FuncFlag dd    0ffffffffh        ;supported functions
  4268.   HotKey   db    0            ;Scan code of hotkey to use
  4269.   ShiftSt  db    0            ;shift state to use for popup
  4270.   HotFlag  db    0            ;Which hotkey is in use
  4271.   ExtCnt   db    0            ;number of extra hotkeys
  4272.   ExtHot   dd    0            ;pointer to extra hot keys
  4273.   Status   dw    0            ;TSR status flags
  4274.   OurPSP   dw    0            ;our PSP segment
  4275.   OurDTA   dd    0            ;our DTA region
  4276.   DSeg     dw    0            ;User's Default Data Segment
  4277.   
  4278.   <<NOTE:   This  is  only  a  partial  listing  of  the  full  TsrParms
  4279.   structure;     see  the  complete  TesSeRact  documentation  for  more
  4280.   details>>
  4281.  
  4282. For minimal  support of  the TesSeRact  Standard,  Multiplex  Function  01h
  4283. should  return   a  FAR   pointer  to  a  data    area  that  contains  the
  4284. Identification String,  Identification Number,  and FuncFlag members.  This
  4285. function is called as follows:
  4286.   
  4287.   mov      ax,5453h
  4288.   mov      bx,01h
  4289.  
  4290.  
  4291.  
  4292.     Copyright (c) 1988, TesSeRact Development Team, All Rights Reserved
  4293.  
  4294.  
  4295. Page 68                             TesSeRact(TM) Documentation (Ver. 1.00)
  4296.  
  4297.  
  4298.   mov      cx,TsrIdNum
  4299.   int      2fh
  4300.  
  4301. If the  Identification Number  in CX matches the TSR's ID Number (which was
  4302. returned by  Multiplex Function  00h), the  TSR should  return  with  ES:BX
  4303. pointing to the TsrParms area and AX equal to zero.
  4304.  
  4305. The FuncFlag  is a  bit-mapped, four-byte variable that shows all Multiplex
  4306. functions that this TSR supports.  This variable is mapped as follows:
  4307.   
  4308.   Bit 0          Function 00h (check install -- REQUIRED)
  4309.   Bit 1          Function 01h (return userparms -- REQUIRED)
  4310.   Bit 2          Function 02h (check hotkey)
  4311.   Bit 3          Function 03h (replace INT 24h)
  4312.   Bit 4          Function 04h (return Data Pointer)
  4313.   Bit 5          Function 05h (set extra hotkeys)
  4314.   Bits 6-7       Undefined -- reserved for future use
  4315.   Bit 8          Function 10h (enable TSR)
  4316.   Bit 9          Function 11h (disable TSR)
  4317.   Bit 10         Function 12h (release TSR from RAM)
  4318.   Bit 11         Function 13h (restart TSR)
  4319.   Bit 12         Function 14h (get current status)
  4320.   Bit 13         Function 15h (set TSR status)
  4321.   Bit 14         Function 16h (get popup type)
  4322.   Bit 15         Undefined -- reserved for future use
  4323.   Bit 16         Function 20h (Call user procedure)
  4324.   Bit 17         Function 21h (stuff keyboard)
  4325.   Bits 18-31     Undefined -- reserved for future use
  4326.  
  4327. If the  TSR supports  the particular  function, the  bit should be SET (1).
  4328. Otherwise, it  should be  zero.   Note that  a  product  using  TesSeRact's
  4329. Library will return with FuncFlag set to (hex) FFFFFFFF.  Other TSRs should
  4330. set the undefined variables to '0' to differentiate themselves.
  4331.  
  4332. The other TesSeRact Multiplex Functions are described in complete detail in
  4333. the full  TesSeRact documentation.   In  addition, any  developer wishing a
  4334. copy of the source code for TesSeRact's Interrupt 2Fh Multiplex Handler may
  4335. receive it by sending a self-addressed, stamped envelope to:
  4336.   
  4337.      TesSeRact Development Team
  4338.      c/o Chip Rabinowitz
  4339.      2084 Woodlawn Avenue
  4340.      Glenside, PA 19038
  4341.  
  4342. For more  information contact  the TesSeRact  Development Team at the above
  4343. address, or at Compuserve 70731,20, or MCIMAIL 315-5415 (TESSERACT).
  4344.  
  4345.  
  4346.  
  4347.  
  4348.  
  4349.  
  4350.     Copyright (c) 1988, TesSeRact Development Team, All Rights Reserved
  4351.  
  4352.  
  4353. TesSeRact(TM) Documentation (Ver. 1.00)                             Page 69
  4354.  
  4355.  
  4356.             Appendix A.  Quick Reference to TesSeRact Functions
  4357.   
  4358.   
  4359.   External Functions
  4360.      TsrMain -- Entry Point for Popup Routine
  4361.      TsrBackCheck -- Check to see if background processing is requested
  4362.      TsrBackProc -- Background Processing Procedure
  4363.      TsrTimerProc -- Periodic Timer Procedure
  4364.      TsrUserProc -- Interface for External Processing
  4365.      TsrCleanUp -- Initialize or Clean Up TSR
  4366.   TesSeRact Library Routines
  4367.      TsDoInit -- Initializes variables and goes resident
  4368.      TsSetStack -- Sets stacks to be used by resident routines
  4369.      TsCheckResident -- Determine if program has been loaded
  4370.      TsVerify2F -- Verify Interrupt 2Fh has valid handler
  4371.      TessBeep -- Call TesSeRact Internal Beep Routine
  4372.   TesSeRact Multiplex Functions
  4373.      Initialization and Information Routines
  4374.           Check Install
  4375.           TsGetParms()
  4376.           TsCheckHotkey()
  4377.           TsSetUser24()
  4378.           TsGetData()
  4379.           TsSetExtraHot()
  4380.      TSR Manipulation and Status Routines
  4381.           TsEnable()
  4382.           TsDisable()
  4383.           TsRelease()
  4384.           TsRestart()
  4385.           TsGetStat()
  4386.           TsSetStat()
  4387.           TsGetPopType()
  4388.      TSR Utility Routines
  4389.           TsCallUserProc()
  4390.           TsStuffKeyboard()
  4391.      
  4392.  
  4393.  
  4394.  
  4395.  
  4396.  
  4397.  
  4398.  
  4399.  
  4400.  
  4401.  
  4402.  
  4403.  
  4404.  
  4405.  
  4406.  
  4407.  
  4408.     Copyright (c) 1988, TesSeRact Development Team, All Rights Reserved
  4409.  
  4410.  
  4411. Page 70                             TesSeRact(TM) Documentation (Ver. 1.00)
  4412.  
  4413.  
  4414.                      Appendix B.  Keyboard Scan Codes
  4415.  
  4416. Please note  that these are not ALL the scan codes available, just the most
  4417. common ones  you will  be using  for TSRs.  Also, for Z-100 computers using
  4418. the ZPC  Hardware Modifications,  TSRPOPLSHIFT  and  TSRPOPRSHIFT  are  not
  4419. usable, since this machine does not distinguish between the two.
  4420.  
  4421. For  those  who  are  not  familiar  with  the  notation,  '0x'  denotes  a
  4422. hexadecimal number.
  4423.   
  4424.   TSRHOT_A        equ    0x1E       TSRHOT_B        equ    0x30
  4425.   TSRHOT_C        equ    0x2E       TSRHOT_D        equ    0x20
  4426.   TSRHOT_E        equ    0x12       TSRHOT_F        equ    0x21
  4427.   TSRHOT_G        equ    0x22       TSRHOT_H        equ    0x23
  4428.   TSRHOT_I        equ    0x17       TSRHOT_J        equ    0x24
  4429.   TSRHOT_K        equ    0x25       TSRHOT_L        equ    0x26
  4430.   TSRHOT_M        equ    0x32       TSRHOT_N        equ    0x31
  4431.   TSRHOT_O        equ    0x18       TSRHOT_P        equ    0x19
  4432.   TSRHOT_Q        equ    0x10       TSRHOT_R        equ    0x13
  4433.   TSRHOT_S        equ    0x1F       TSRHOT_T        equ    0x14
  4434.   TSRHOT_U        equ    0x16       TSRHOT_V        equ    0x2F
  4435.   TSRHOT_W        equ    0x11       TSRHOT_X        equ    0x2D
  4436.   TSRHOT_Y        equ    0x15       TSRHOT_Z        equ    0x2C
  4437.   TSRHOT_0        equ    0x0b       TSRHOT_1        equ    0x02
  4438.   TSRHOT_2        equ    0x03       TSRHOT_3        equ    0x04
  4439.   TSRHOT_4        equ    0x05       TSRHOT_5        equ    0x06
  4440.   TSRHOT_6        equ    0x07       TSRHOT_7        equ    0x08
  4441.   TSRHOT_8        equ    0x09       TSRHOT_9        equ    0x0A
  4442.   TSRHOT_F1       equ    0x3B       TSRHOT_F2       equ    0x3C
  4443.   TSRHOT_F3       equ    0x3D       TSRHOT_F4       equ    0x3E
  4444.   TSRHOT_F5       equ    0x3F       TSRHOT_F6       equ    0x40
  4445.   TSRHOT_F7       equ    0x41       TSRHOT_F8       equ    0x42
  4446.   TSRHOT_F9       equ    0x43       TSRHOT_F10      equ    0x44
  4447.   ;
  4448.   ;Enhanced Keyboards only
  4449.   ;
  4450.   ;May not work with all computers, keyboards
  4451.   ;
  4452.   TSRHOT_F11      equ    0x57       TSRHOT_F12      equ    0x58
  4453.   ;
  4454.   ;#defines for ShiftState
  4455.   ;
  4456.   TSRPOPRSHIFT    equ    0x01       TSRPOPLSHIFT    equ    0x02
  4457.   TSRPOPCTRL      equ    0x04       TSRPOPALT       equ    0x08
  4458.   
  4459.  
  4460.  
  4461.  
  4462.  
  4463.  
  4464.  
  4465.  
  4466.     Copyright (c) 1988, TesSeRact Development Team, All Rights Reserved
  4467.  
  4468.  
  4469. TesSeRact(TM) Documentation (Ver. 1.00)                             Page 71
  4470.  
  4471.  
  4472.                         Appendix C.  Reporting Bugs
  4473.  
  4474. Bugs  found  in  the  RELEASE  version  of  TesSeRact  should  be  reported
  4475. immediately to  the TesSeRact  Development  Team  at  Compuserve  70731,20,
  4476. MCIMAIL 315-5415,  or at  1-215-884-3373.   The Development  Team will make
  4477. every reasonable  effort to  repair said bug in the minimum amount of time.
  4478. Registered users  who  report  verifiable  bugs  or  who  make  enhancement
  4479. suggestions  that   are  implemented  in  TesSeRact  receive  an  automatic
  4480. registration to  the next  version of  TesSeRact  or  a  free  source  code
  4481. license.
  4482.  
  4483. When  reporting  bugs,  please  provide  as  MUCH  information  about  your
  4484. configuration as  possible; e.g.,  hardware manufacturer, BIOS manufacturer
  4485. and version  number, DOS  OEM info  and version  number, other Ram-Resident
  4486. software and  device drivers,  other hardware,  etc.   The more information
  4487. provided the Development Team, the better our response to your problems.
  4488.  
  4489. Technical Support  for TesSeRact  is provided free of charge in Subtopic 13
  4490. of  the   Computer  Language  Magazine  Forum  (GO  CLMFOR)  on  CompuServe
  4491. Information Service.
  4492.  
  4493.  
  4494.  
  4495.  
  4496.  
  4497.  
  4498.  
  4499.  
  4500.  
  4501.  
  4502.  
  4503.  
  4504.  
  4505.  
  4506.  
  4507.  
  4508.  
  4509.  
  4510.  
  4511.  
  4512.  
  4513.  
  4514.  
  4515.  
  4516.  
  4517.  
  4518.  
  4519.  
  4520.  
  4521.  
  4522.  
  4523.  
  4524.     Copyright (c) 1988, TesSeRact Development Team, All Rights Reserved
  4525.  
  4526.  
  4527. Page 72                             TesSeRact(TM) Documentation (Ver. 1.00)
  4528.  
  4529.  
  4530.                                  Glossary
  4531.  
  4532. This glossary  is not intended to contain a complete description of all the
  4533. technical terms  used in  this document;  it does,  however, describe those
  4534. terms that relate to the topic of Ram-Resident programming.  For details on
  4535. other terms, see other, more complete technical documentation about MS-DOS.
  4536.  
  4537.   Assembly Language:   A  set of instructions, written in human-readable
  4538.      form, that can be translated directly into the machine code used by
  4539.      a computer.   This  is generally  the lowest-level language used by
  4540.      programmers.
  4541.  
  4542.   Compiler:     A  computer   program  that  converts  the  source  code
  4543.      instructions written in a high-level language (such as C or Pascal)
  4544.      into either  assembly language  or machine  code.   Some  compilers
  4545.      produce an  intermediate 'object'  file, which  contains additional
  4546.      information not  needed by  the executable  code, but used by other
  4547.      programming utilities.
  4548.  
  4549.   Data Structure:   A set of information, grouped together in a logical,
  4550.      pre-defined sequence.
  4551.  
  4552.   Disk Transfer Address:  This is a buffer used by some DOS functions to
  4553.      transfer file data or information.
  4554.  
  4555.   DOS:  Disk Operating System.  See also MS-DOS.
  4556.  
  4557.   DTA (see Disk Transfer Address)
  4558.  
  4559.   Graphics Mode:  A type of video display mode that allows addressing of
  4560.      individual graphic elements on the screen.
  4561.  
  4562.   Hot Key:   The keystroke or combination of keystrokes that can be used
  4563.      to popup a Ram-Resident program
  4564.  
  4565.   Memory Resident (See Terminate But Stay Resident)
  4566.  
  4567.   Memory Size  The amount of memory used by a Ram-Resident Program.
  4568.  
  4569.   MS-DOS:   Microsoft's Disk  Operating System,  originally designed for
  4570.      the IBM-PC, now used by all IBM-compatible computers.
  4571.  
  4572.   Multiplex Function:   A  TesSeRact Function  that  may  be  called  by
  4573.      external programs through the DOS Multiplex Interrupt (2Fh).
  4574.  
  4575.   PC-DOS (See MS-DOS)
  4576.  
  4577.  
  4578.  
  4579.  
  4580.  
  4581.  
  4582.     Copyright (c) 1988, TesSeRact Development Team, All Rights Reserved
  4583.  
  4584.  
  4585. TesSeRact(TM) Documentation (Ver. 1.00)                             Page 73
  4586.  
  4587.  
  4588.   Program Segment  Prefix:   A 256-byte  header that  DOS puts in memory
  4589.      immediately before all .EXE or .COM programs prior to executing the
  4590.      program.   It contains  various information  used by DOS to control
  4591.      the executing of the program.
  4592.  
  4593.   Popup:  Used in two ways:  'To Popup' a program is to call the primary
  4594.      routine (TsrMain()) used to run the Ram-Resident Program, generally
  4595.      through the  use of  a Hotkey;  also, 'A  Popup' program is another
  4596.      name for a Ram-Resident Program.
  4597.  
  4598.   PSP (see Program Segment Prefix)
  4599.  
  4600.   Ram-Resident (See Terminate But Stay Resident)
  4601.  
  4602.   Shareware:   A method  of distributing  software programs  that allows
  4603.      users the  opportunity to  'test drive'  a software  program before
  4604.      paying for it.
  4605.  
  4606.   Stack   An area  in memory where the processor maintains addresses for
  4607.      control information.   It  is also  used by  executing programs  to
  4608.      store temporary data.
  4609.  
  4610.   Terminate But  Stay Resident:   A program that is kept in memory after
  4611.      it terminates,  in order to provide a useful function.  The TSR may
  4612.      be a Popup program, or it may be a background program, or it may be
  4613.      a combination of the two.
  4614.  
  4615.   Text Mode:  A type of video display mode that automatically translates
  4616.      video information  into the appropriate graphic elements to display
  4617.      characters.
  4618.  
  4619.   TSR (See Terminate But Stay Resident)
  4620.  
  4621.   Video Mode:   An  identification number that describes how the current
  4622.      display information is being interpreted (i.e., text or graphics).
  4623.  
  4624.  
  4625.  
  4626.  
  4627.  
  4628.  
  4629.  
  4630.  
  4631.  
  4632.  
  4633.  
  4634.  
  4635.  
  4636.  
  4637.  
  4638.  
  4639.  
  4640.     Copyright (c) 1988, TesSeRact Development Team, All Rights Reserved
  4641.  
  4642.  
  4643. Page 74                             TesSeRact(TM) Documentation (Ver. 1.00)
  4644.                                      
  4645.                                    Index
  4646.  
  4647.   _TESS_CPYRT....................16       Hercules Graphics Card.........11
  4648.   _TESS_ENDOFDATA................16       Hot Key........................72
  4649.   _TESS_ERROR24..................16       Hotkeyiv, 12, 15, 16, 17, 19, 21,
  4650.   _TESS_INTERRUPTRETURN..........16         30, 37, 40, 54, 61, 62, 66, 67,
  4651.   _TESS_TEMPPARMS................16         73
  4652.   _TESS_VIDMODE..............11, 16       HOTKEYON.......................17
  4653.   _TESS_VIDPAGE..............11, 16       IBMNET.........................10
  4654.   _TESSDOPOPUP...................14       Identification Number.15, 28, 35,
  4655.   _TESSRESTOREINTS...............12         36, 38, 39, 40, 42, 43, 44, 45,
  4656.   _TESSSETUPINTS.................12         46, 47, 48, 50, 51, 53, 54, 60,
  4657.   Assembler......12, 18, 33, 34, 58         67, 68
  4658.   Assembly Language..............72       Identification String...2, 5, 15,
  4659.   ASSIGN.COM.............iv, 59, 65         28, 35, 53, 54, 59, 60, 61, 66,
  4660.   Association of Shareware                  67
  4661.     Professionals..............7, 8       INDOS......13, 14, 17, 30, 48, 63
  4662.   Background.....................53       INT28ACTIVE....................17
  4663.   BACKSET........................17       Interrupt 2Fh..iv, 3, 34, 59, 64,
  4664.   BIOS...............iv, 19, 20, 71         65
  4665.   Borland International........3, 4       Library...iv, vi, 1, 3, 4, 5, 12,
  4666.   Bugs.....................v, 6, 71         15, 18, 19, 26, 32, 33, 34, 44,
  4667.     reporting....................71         55, 58, 59, 62, 65, 68
  4668.   Check Hotkey...................34       License.........................5
  4669.   Check Install..............34, 59         General.......................1
  4670.   CLMFOR......................6, 71         Registered User...............2
  4671.   CLMFORUM.......................10         Source Code...................3
  4672.   Compiler.......................72         Special....................4, 5
  4673.   CompuServe..vii, 3, 4, 6, 10, 64,       MCIMAIL.......3, 4, 6, 64, 68, 71
  4674.     68, 71                                Memory30, 35, 43, 44, 45, 58, 60,
  4675.   Computer Language Magazine Forum          61, 62, 63
  4676.     6, 71                                   allocation...............55, 56
  4677.   Critical Error.................13         Expanded.....................10
  4678.   Critical Error Flag........14, 30         Extended.....................10
  4679.   Disk Transfer Address.13, 15, 19,       Memory resident.............v, 72
  4680.     21, 67, 72                            Memory Size....................72
  4681.   DOSiv, v, 13, 14, 16, 19, 20, 21,       Microsoft..iv, v, 18, 26, 56, 58,
  4682.     22, 24, 30, 32, 35, 38, 48, 59,         72
  4683.     61, 63, 65, 71, 72, 73                Microsoft Word.................11
  4684.   DOS Technical Reference Manual38,       MS-DOS.....................59, 72
  4685.     61                                    MS-DOS Encyclopedia.............v
  4686.   ExtraHot...........12, 16, 40, 53       Multiplex..iv, vi, 3, 14, 15, 23,
  4687.   EXTRAHOTSET....................17         24, 28, 34, 36, 39, 41, 42, 49,
  4688.   EXTRAINT24.....................17         54, 59, 60, 61, 62, 64, 65, 68,
  4689.   Freeware.....................1, 3         72
  4690.   FuncFlag...............60, 67, 68       Newsletter......................5
  4691.   FuncFlags......................15       NOPOPCOMMAND...................17
  4692.   Graphics...............11, 14, 17       NOPOPGRAPH.................11, 17
  4693.   Graphics Mode..................72       PC-DOS.....................59, 72
  4694.   Hercules.......................11       POPFF..........................16
  4695.  
  4696.  
  4697.  
  4698.     Copyright (c) 1988, TesSeRact Development Team, All Rights Reserved
  4699.  
  4700.  
  4701. TesSeRact(TM) Documentation (Ver. 1.00)                             Page 75
  4702.                                      
  4703.                                    Index
  4704.  
  4705.   Popup.11, 13, 14, 15, 17, 33, 48,       TsrBackCheck..20, 21, 48, 53, 57,
  4706.     53, 57, 63, 67, 68, 73                  63
  4707.   POPUPSET.......................17       TsrBackProc...20, 21, 23, 48, 53,
  4708.   PRINT.COM..............iv, 59, 65         57, 63
  4709.   Program Segment Prefix13, 15, 19,       TsrCleanUp24, 34, 38, 40, 45, 53,
  4710.     21, 23, 67, 73                          54, 55, 57, 61, 62, 63
  4711.   Ram-Resident...............iv, 73       TsrData....12, 13, 39, 48, 62, 63
  4712.   RUN-TIME LIBRARY...............56       TsRelease......................44
  4713.   SHARE.COM..............iv, 59, 65       TSRENABLED.....................17
  4714.   Shareware.......1, 3, 5, 7, 8, 73       TsRestart..................28, 45
  4715.   SHIFTSON.......................17       TsrFlags...17, 19, 30, 46, 47, 63
  4716.   Source code.v, 1, 2, 3, 5, 6, 64,       TsrIntTable................12, 13
  4717.     68, 71, 72                            TsrMain...14, 15, 16, 19, 21, 48,
  4718.   Stack.13, 19, 20, 21, 22, 24, 26,         53, 57, 63, 73
  4719.     53, 55, 56, 73                        TsrParms..12, 15, 19, 36, 46, 60,
  4720.     Background...........15, 23, 26         61, 63, 67, 68
  4721.     Popup................15, 24, 26       TSRRELEASED....................17
  4722.   Stack-checking.............19, 26       TsrStatus......15, 16, 17, 46, 63
  4723.   Terminate But Stay Residentiv, 73       TsrTimerProc...........22, 53, 57
  4724.   TESS-TP.TPU....................iv       TSRUSEBACK.................17, 20
  4725.   TESS.H.....................12, 17       TSRUSEPOPUP................17, 19
  4726.   TESS.INC...................12, 17       TsrUserProc23, 50, 53, 54, 57, 63
  4727.   TESS.LIB.......................iv       TSRUSETIMER....................17
  4728.   TESS.TP4...............12, 17, 57       TSRUSEUSER.....................17
  4729.   TESS_BP.OBJ....................58       TsSetAdrTP4................18, 57
  4730.   TESS_END.OBJ...................58       TsSetExtraHot.12, 16, 17, 19, 24,
  4731.   TESS_GLOBALS...................13         40
  4732.   TESS_USERPARMS.................15       TsSetStack.........19, 25, 26, 54
  4733.   TessBeep...............11, 25, 33       TsSetStat......................47
  4734.   TESSINITSTART..................58       TsSetUser24................14, 38
  4735.   TESSPARK...................14, 58       TsStuffKeyboard................51
  4736.   TESSTP.TPU.....................24       TsVerify2F.....25, 32, 35, 59, 61
  4737.   Text Mode......................73       Tutorial.......................53
  4738.   TIMERSET.......................17       USERPROCON.....................17
  4739.   TsCallUserProc.................50       Video mode.............11, 16, 73
  4740.   TsCheckHotkey..............37, 54       Warranty........................2
  4741.   TsCheckResident...15, 25, 28, 32,
  4742.     34, 35, 54, 61
  4743.   TsDisable..............42, 43, 62
  4744.   TsDoInit..11, 12, 15, 17, 24, 25,
  4745.     28, 34, 35, 38, 40, 46, 47, 54,
  4746.     58, 61, 62, 63
  4747.   TsEnable...............42, 43, 62
  4748.   TsGetData......................39
  4749.   TsGetParms.....................36
  4750.   TsGetPopType...................48
  4751.   TsGetStat..............46, 47, 63
  4752.   TSRACTIVE......................17
  4753.  
  4754.  
  4755.  
  4756.     Copyright (c) 1988, TesSeRact Development Team, All Rights Reserved